-
Notifications
You must be signed in to change notification settings - Fork 11
Routing
Basecoat uses named routes and a traversal/hierarchical approach to processing routes. Rather than a full URL representing a single route, each "directory" in the URL is placed on a "stack" and processed as an individual route. Each route can continue processing the next item in the stack or modify the behavior/stack based on the current state. This approach is based on the concept that top level routes need to run some code common to the subroutes and can act as a gatekeeper and/or preparer. This setup also allows the registering of routes on demand, only when needed. It is the job of the parent route to configure and register all the valid subroutes.
For example, if a route and it's subroutes requires a user to be logged in, the parent route can check to see if the user is logged in. If the user is not logged, the route stack can be modified so that the next route to load is the login route instead of the requested route(s). This also allows the loading of any route under any URL, largely doing away with the need for expensive redirects.
All route functions, methods and variables are referenced via the routing instance.Load initial routes using an associative array of route configurations. See Configuration section for options.
$basecoat->routing->setRoutes( array )
Add additional routes after the initial routes are loaded. Routes with the same name will be overwritten.
$basecoat->routing->addRoutes( array )
The function/file configuration options indicate which controller(s) to use to process the route (see Route Configuration in the Configuration section). If both are declared, both are executed with the function being run first. This allows simple routes to be declared as functions and larger routes to be declared as files that are included. By declaring both, the function can run pre-check code to see if the required file should be loaded (i.e. login check), or configure the environment.
Custom route parameters and meta data is support and can be read and processed by your routing code. For example, adding a "log_prefix" or "require_login" option that can be checked and used for processing.
The default URL to process is the currently requested URL. Optionally set a different URL to process, typically used on the command line for unit testing or running scripts.
Allow Basecoat to automatically start the processing of the current URL by calling this function. An optional URL parameter can be provided to process a URL other than the requested one. Typically this would be done for unit tests or command line processing where multiple "URLs" need to be processed and this function is called multiple times.
Basecoat will only process the first route in the URL, it is up to the route controller to call the next route in the stack by calling
runNext(). This allows other routes to be run, new routes registered, configurations changed, before the next route is processed. Since routing is hierarchical, subroute configurations are loaded dynamically using the addRoutes() method. Typically additional route configurations are registered by the current route controller.
Typical processing flow:
+ route controller executed
+ route controller configures/registers subroutes
->runNext()called
repeat as needed
Run a configured route. Pass the name of the route as configured in the registered routes array. This function can be called whether there is another route on the stack to process or not. If there are no more routes on the route stack, control simply returns to Basecoat for final processing.
URL: http://example.com/route1/route2/
Route stack: route1, route2
$basecoat->routing->run_routes = array('route1', 'route2');index.php loads primary routes and initiates processing
// Configure and set routes $routes = array( 'route1' => array( 'file' => 'route1.php', 'template' => 'route1.tpl.php', ), ); $basecoat->routing->setRoutes($routes);// Process current URL $basecoat->processRequest();
route1.php processes first route on the stack, loads subroutes
// Add route content to page $content = $basecoat->view->newView(); $content->processTemplate($basecoat->view->templates_path . $basecoat->routing->current['template']); $content->addToView($basecoat->view); // Configure and register new routes $routes = array( 'route2' => array( 'file' => 'route2.php', 'template' => 'route2.tpl.php', ), ); $basecoat->routing->addRoutes($routes); $basecoat->routing->runNext();
route2.php processes next route on stack, loads subroutes
// Add route content to page $content = $basecoat->view->newView(); $content->processTemplate($basecoat->view->templates_path . $basecoat->routing->current['template']); $content->addToView($basecoat->view);// Always safe to call, even if no more routes to run $basecoat->routing->runNext();
Basecoat provides some built-in functionality for certain standard default routes. These special routes are: static, undefined. They are used for processing static content files and to process an undefined route respectively.
The static route is used for processing static content files (i.e. html) and merging them with the configured layout. There is no need to configure a route for each file if the file has no special processing requirements. When a requested URL is not found in the configured route list, the static templates directory will be checked for a file with a matching name. Both the "route" name and the route name + .html are checked. The route name is sanitized (leading and trailing / and spaces are removed) before checking the for a file. If a file exists, an alias of the "static" route will be dynamically configured and run.
By default, a route called static should always be configured. The name of this route can be customized with the setStatic([routename]) method.
If there is no matching configured route found, and no static file matching the requested route, then the undefined route will be run. By default, a route called undefined should always be configured. The name of this route can be customized with the setUndefined([routename]) method.
The original route that was requested to be run, persists through all routes.
The list of routes to be run. This is treated as a stack, whereby each route is taken off the top and run. The runNext() method is used to process and remove the next route in the stack.
The name of the current route being run.
The configuration information about the currently running route.
Array of profiling information for each route run and how long it took. Helpful for debugging and performance tuning.
// Example output of profiling with 1 route run
Array
(
[start] => 1355678392.207
[routes] => Array
(
[0] => Array
(
[route] => /
[time] => 0.00099992752075195
[start] => 1355678392.207
[end] => 1355678392.208
[seq] => 1
)
)
)