Documentation home Table of contents Module index Class index

AnewtURLDispatcher class

Class Overview

Dispatcher that routes requests to request handler methods.

Well-designed web applications use a clean URL scheme for all pages and resources in the application. Read ‘Cool URIs don't change’ to find out why this is important. Clean web applications do not need ugly .php extensions or weird HTTP GET parameters with cryptic numbers or strange identifers. Instead, you are encouraged to use clean URLs, e.g. /user/USERNAME for a user page.

AnewtURLDispatcher offers the basic functionality to implement web applications that use clean URLs. AnewtURLDispatcher processes incoming requests and looks at the URL of the request to decide which piece of code should be invoked to handle that request. This means that AnewtURLDispatcher is at the heart of your application: it is the main entry point for all the functionality your application offers.

AnewtURLDispatcher is based around two main concepts: commands and routes.

Commands

Commands are methods that do the actual work, like building an output page. Commands are regular methods on your AnewtURLDispatcher subclass, and look like command_xyz(), where xyz is the name of the command. What you would normally create a separate PHP file for, e.g. users.php, you can now write as a simple method, e.g. command_users(). Other related pages are just additional methods on the same class. AnewtURLDispatcher allows you to group related functionality together in one file, e.g. a user page, an ‘edit user’ page, or a ‘new user’ page. (Note that if you insist you can still require_once('latest-news.php') in your command method, though this is not how AnewtURLDispatcher is intended to be used).

Routes

Routes define how URLs map to commands. This is where you define your URL scheme and say which command should be executed when AnewtURLDispatcher processes an incoming request. The section on routes below explains how routes work in more detail.

Getting Started

Getting started with AnewtURLDispatcher is not hard. You define the URLs you want your application to respond to, and implement the corresponding commands. It is really straight-forward:

• Subclass AnewtURLDispatcher
• Change some settings if you're not happy with the defaults
• Add routes to map URLs to commands
• Implement commands to actually make your application do something useful, just like would do otherwise.

Setting up clean URLs for the Apache web server can be done using this .htaccess snippet. This instructs Apache to invoke dispatch.php for all URLs that do not point to an existing file (such as a static HTML page or image files, which are not served through the dispatcher).

Since AnewtURLDispatcher takes care of the complete request, the only thing the dispatch.php file should do is something like this:

Handling Errors

If no command to execute can be found, e.g. because none of the routes match, an AnewtHTTPException will be thrown. Additionally, if you want to raise an error from your command, e.g. because a requested database record does not exists, you can throw an AnewtHTTPException yourself. This will cause a ‘HTTP 404 Not Found’ error page to be shown. Example:

To create your own error handlers, override the error handling methods, e.g. handle_error_not_found(). See below for more information.

Properties

The following properties influence how AnewtURLDispatcher behaves:

• force-trailing-slash indicates whether a trailing slash should be enforced on URLs that do not have one, by redirecting the request to the correct URL. This only applies to GET requests with URLs that do not contain a filename extension. This property is true by default.
• use-automatic-commands indicates whether the first part of the url should be used to find a matching command in case none of the explicitly added routes match, e.g. if the url /foo/bar/baz does not match any route, but the dispatcher has a command_foo() method, that is automatically invoked. This property is false by default, since it may have unwanted side effects when used in combination with explicit routes. Furthermore, it is often desirable to design your application's URLs explicitly instead of relying on automatic behaviour.
• default-command defines the default command that is invoked if no other routes the current URL. This fallback feature is disabled by default (defaults to null).

When a command is invoked, you can use the following properties to get the URLs of the current request:

• url-relative contains the relative URL rooted at the dispatcher root
• url-prefix is the prefix where the dispatcher resides
• url-full is the complete URL, i.e. both url-prefix and url-relative

For routes based on URL parts, constraints that should apply to all routes (instead of to just one route) can be configured:

• constraints is an associative array that maps parameter names to regular expressions. See the section on routes below for more information.

Public Methods ¶

Route Methods ¶

Routes define how URLs map to commands. Whenever a route matches the request, the corresponding command is invoked to handle the request. Command methods get passed a $parameters argument containing values for parameters that were defined when setting up the route (either regular expression matches, or named parameters, depending on the type of URL route).

Incoming requests will be matched against all defined routes, until a route matches the current request, in which case the associated command is invoked. The routes are tried in the order in which they are added to the dispatcher. Therefore you should add more specific routes before more general routes.

If you decide to use automatic commands, those will be tried if none of the explicitly defined routes matched the request. See the automatic-commands property description for more details on this feature.

In addition to explicitly created routes, you can also add a default command that will be invoked if none of the routes match. The default command will be invoked if none of the provided URL routes (both explicit routes and automatic commands, if enabled) match the request URL. This method can be used to supply default functionality. Note that this is not the right way to handle errors; use handle_error_not_found() or one of the other error callbacks instead.

Two types of routes can be used (read on for an explanation on both):

1. using regular expressions
2. using URL parts

Regular expression routes use a regular expression to match an URL, and can be added using AnewtURLDispatcher::add_route_regex(). The URL that is used for matching does not contain a leading /, so you should not specify this in the regular expression.

To extract parameters from the URL, the $parameters array passed to the command contains the matches from preg_match(), i.e. the parenthesized expressions. Parameters can have names (instead of numbers) by using named matches, e.g. (?P<year>\d{4}). See below for more information about how regular expressions are used.

Examples for routes using regular expressions:

Routes based on URL parts are the other way to define URL routes. These routes can be added using AnewtURLDispatcher::add_route_url_parts(). To define a route, you can provide either a URL string, or an array of URL parts. An URL part corresponds to a "path component" in the URL, e.g. the URL /news/2009/06/ consists of three parts.

For routes based on URL parts, parameters can be specified using a : character before the parameter name, e.g. :year The constraints used for the parameters are regular expressions that will be matched using preg_match(). If no constraint is specified for a parameter, no checking is performed (any value is accepted). See below for more information about how regular expressions are used.

Examples for routes using URL parts:

Constraints should be provided as an associative array that maps parameter names to regular expressions. The constraints in the constraints property apply to all routes using URL parts, but can be overridden by specifying additional constraints when calling AnewtURLDispatcher::add_route_url_parts().

Note about the regular expressions used for URL and parameter matching: the pattern is passed directly to preg_match(). Make sure to include ^ and $ appropriately to match the full string, since otherwise you might match URLs that you do not want to match! Hint: use a # character for the regular expression delimiter, since the often-used / is confusing because it is a common character in URLs. (A literal # cannot occur in URLs anyway since it is used for the client-side fragment specifier.)

Dispatching Methods ¶

Callback Methods ¶

Error Handling Methods ¶

A command may throw an AnewtHTTPException (or another exception) to indicate something went wrong during the request. In this case, AnewtURLDispatcher::dispatch() will invoke the AnewtURLDispatcher::handle_error() method with the exception that was thrown.

The common "HTTP 404 Not Found" and "HTTP 403 Forbidden" cases have their own convenience error handler methods that you can override: AnewtURLDispatcher::handle_error_not_found() and AnewtURLDispatcher::handle_error_forbidden(). All other errors are passed directly to AnewtURLDispatcher::handle_error().

Private Attributes ¶

Inheritance

Base Classes

• AnewtURLDispatcher
• AnewtContainer

Inherited members

• AnewtContainer::_to_array()
• AnewtContainer::_add()
• AnewtContainer::delete()
• AnewtContainer::get()
• AnewtContainer::_isset()
• AnewtContainer::_seed()
• AnewtContainer::setdefault()
• AnewtContainer::getdefault()
• AnewtContainer::set()
• AnewtContainer::__isset()
• AnewtContainer::__set()
• AnewtContainer::__construct()
• AnewtContainer::is_set()
• AnewtContainer::add()
• AnewtContainer::_getdefault()
• AnewtContainer::__unset()
• AnewtContainer::seed()
• AnewtContainer::to_array()
• AnewtContainer::_get()
• AnewtContainer::__get()
• AnewtContainer::keys()
• AnewtContainer::clear()
• AnewtContainer::_keys()
• AnewtContainer::_set()