Routing to an internal URI

Let's now customize the routes used to channel web requests into actions we will create for our app. When a request comes in to the webserver, the Q_Dispatcher uses the routes to translate the requested URL into an internal URI, which is basically an object $uri that contains at least the fields $uri->action and $uri->module.

In your PHP code, you can access this information as follows:

// returns the requested URL:
$url = Q_Request::url();

// returns the base URL of your app,
// parent of the /css and other paths
$base_url = Q_Request::baseUrl();

// return value may end with "/index.php"
// depending on the web request
$controller_url = Q_Request::baseUrl(true);

// returns the $uri object obtained
// from routing the URL
$uri = Q_Dispatcher::uri();

Take a look at your APP_DIR/config/app.json file. The Q/routes config field specifies the routes using an associative array. The keys of the array are patterns against which Qbix tries to match the tail of the requested URL. The process is as follows:

• The tail (e.g. foo/bar/baz) is split into segments by '/' (slashes)
• The routes from the config are examined from last to first, until a matching route is found. The "Q"/"routes@start" config is checked first, then "Q"/"routes" and finally "Q"/"routes@end"
• A route matches if its pattern contains matching literal values (foo, bar) in the right places,
• The pattern may also have variables that can match any wildcard. For example, the pattern "foo/:action/baz" matches the tail "foo/bar/baz" and sets the $uri->action field to "bar".
• Some segments can be of the form :variable.literal, which would match "anything.literal". This is useful to mimic files ending in .html, etc. by having patterns such as ":module/:action.html"
• The last segment can be of the form :variable[], which would match "any/number/of/segments" in the URL and map them to an array in the URI.
• If the value of the route is null, this route is skipped in the matching.
• Otherwise, the value of the route should be an associative array of fieldName: string pairs. If the :fieldName is in the pattern, then the string is a RegExp to test the field value against. Otherwise, if the route matches then the field is set to the string value, This is typically used for setting fields (such as $uri->module) that have not been specified by the pattern. For example, "foo/$action": {"module": "foo"}. Finally, you can also include {"": "Your/event/name/here"} to perform any additional processing on the route, and return false to prevent a match.
• If a match is not found, an empty URI is returned.
• By convention, routing is considered successful only if at least $uri->module and $uri->action have been set at the end of it.

Unrouting

To unroute a URI, you call Q_Uri::url($uri), where $uri is a URI object, an array, or a string of the form "$module/$action ".json_encode($more_fields). For example, you can do:

Q_Uri::url("First/welcome ".json_encode(array('facebook' => 1)))

If you want to attach a ?querystring or #fragment to the resulting URL, you would do

Q_Uri::url("First/welcome?querystring#fragment ".json_encode(array('facebook' => 1)))

Unrouting is used a lot by the Q_Html class, which is covered in the article on output. It also makes use of the Q/proxies config field, which is an array consisting of dest url => source url pairs that set up the proxies information.