2.4. Provided Subclasses

2.4.1. Introduction

Zend Framework provides several alternatives to the default classes provided, including alternate request objects, routers, and response objects.

2.4.2. Zend_Controller_Request_Http

Zend_Controller_Request_Http provides a request object for use in an HTTP environment. In addition to extending Zend_Controller_Request_Abstract, it proxies to a Zend_Http_Request object

2.4.3. Zend_Controller_RewriteRouter

2.4.3.1. Introduction

Zend_Controller_RewriteRouter is a new version of the framework router. Routing is the process of taking a URI endpoint and decomposing it to determine which controller and action of that controller, should receive the request. This definition of controller, action and optional parameters is packaged into a value object called Zend_Controller_Dispatcher_Token which is then processed by Zend_Controller_Dispatcher. Routing occurs only once: when the request is initially received and before the first controller is dispatched.

Zend_Controller_RewriteRouter is designed to allow for mod_rewrite like functionality using pure php structures. It is very loosely based on Ruby on Rails routing and does not require any prior knowledge of webserver URL rewriting. It is designed to work with a single mod_rewrite rule (one of):

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php
RewriteEngine on
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 

2.4.3.2. Using a router

To properly use the RewriteRouter you have to instantiate it, add some user defined routes and inject it into the controller. The following code illustrates the procedure:

/* -- create a router -- */

$router = new Zend_Controller_RewriteRouter();
$router->addRoute('user', 'user/:username', array('controller' => 'user', 'action' => 'info'));

/* -- set it in a controller -- */

$ctrl = Zend_Controller_Front::getInstance();
$ctrl->setRouter($router);

2.4.3.3. Basic Routes

The heart of the RewriteRouter is the definition of user defined routes. Routes are created by calling the addRoute method of RewriteRouter:

$router->addRoute('user', 'user/:username');

The first parameter is the name of the route. It is redundant at the moment of writing but will be used in the future in a URL view helper to allow for easy URL generation in your views. Should you need to make use of a previously configured named route, you can retrieve it with the getRoute method of the RewriteRouter.

The second parameter is a route that will be matched to a URL - for example, the above route will match http://example.com/user/martel. The colon in a route marks a URL variable which will be accessible through a Zend_Controller_Action::_getParam method. In our example a parameter named username will be set to a value of 'martel'.

[Note] Note
Routes are matched in reverse order so make sure your most generic routes are defined first.
[Note] Note
For now the current implementation allows for use of any characters except a slash (/) as a variable identifier but it is strongly recommended that one uses only php variable friendly characters. In future the implementation will probably be altered and this may introduce bugs to your code.

There are two special variables which can be used in your routes - 'controller' and 'action'. These special variables will be used to find a controller and/or an action chosen in the URL. The 'action' variable must always be defined either in the route or as a default parameter. The 'controller' variable will default to the IndexController if it is not defined.

$router->addRoute('user', ':controller/:action');

If you point your browser to 'http://example.com/news/latest' with this route defined the Zend_Controller_Dispatcher will invoke the latestAction of your NewsController.

2.4.3.4. Variable defaults

Every variable in the route can have a default. To provide it you have to add a third parameter to the addRoute method. This third parameter is an array with keys as variable names and values as desired defaults.

$router->addRoute('archive', 'archive/:year', array('year' => 2006));

What may not be clearly visible is that the above route will match URLs like 'http://example.com/archive/2005' and 'http://example.com/archive'. In the latter case the variable year will have a value of 2006.

In the above example we haven't set a controller so it will always result in a noRoute action of an IndexController. To make it usable you have to provide a valid controller and a valid action as a default:

$router->addRoute('archive', 'archive/:year', array('year' => 2006, 'controller' => 'archive', 'action' => 'show'));

2.4.3.5. Variable requirements

One can add a fourth parameter where variable requirements can be set. These are defined as regular expressions:

$router->addRoute('archive', 'archive/:year', array('year' => 2006), array('year' => '\d+'));
[Note] Note
Unlike Ruby on Rails, ZF RewriteRouter will match a route and use a default when a fourth parameter variable requirement is not met. So the URL of 'http://example.com/archive/test' will match the above route and set the year to 2006. This functionality may be altered in the future as it is being discussed at the moment of writing of this documentation.

2.4.3.6. Base URL and subdirectories

Unlike the original Router, RewriteRouter can be used in subdirectories - it automatically detects your base URL and sets it accordingly. For example: if you keep your index.php in a webserver subdirectory named /projects/myapp/index.php rewrite base (base URL) will be set to /projects/myapp. This string will then be stripped from the beginning of the path before calculating any route matches. This frees one from the necessity of prepending it to any of your routes. The route of 'user/:username' will match URIs like http://localhost/projects/myapp/user/martel and http://example.com/user/martel.

[Note] Note
Automatic rewrite base is case sensitive, so make sure your URL will match a subdirectory name in a filesystem (even on Windows machines). If it doesn't you will get to noRoute action.

Should rewrite base be detected incorrectly you can override it with your own base path with the help of the setRewriteBase method of the RewriteRouter class:

$router->setRewriteBase('/projects/myapp');
[Note] Note
This step won't be necessary in most cases and is strongly discouraged as it introduces another configuration variable which would have to be altered when one moves code to another directory configuration.

2.4.3.7. Default routes

Zend_Controller_RewriteRouter is preconfigured with two default routes. The first handles your root URL and is mapped to indexAction of IndexController: so you have to provide them as outlined in the Section 2.2, “Getting Started” (see Section 2.2.5, “Default Controller”). The second default route is included to provide compatibility with the first version of the router. It will match URIs in the shape of 'controller/action'.

Default rules are configured as:

// Default route for root URL
$this->addRoute('default', '', array('controller' => 'index', 'action' => 'index'));

// Route for Router v1 compatibility
$this->addRoute('compat', ':controller/:action', array('controller' => 'index', 'action' => 'index'));
[Note] Note
Though Zend_Controller_RewriteRouter is configured for backwards compatibility it will not match controller/action URIs with additional parameters just yet.

2.4.4. Zend_Controller_Response_Http

Zend_Controller_Response_Http is a response object suitable for use in an HTTP environment. It contains methods for setting, retrieving, and clearing headers, and the __toString() method sends all headers at once before returning the response content.

setHeader() takes two arguments, a header type and the header value. A third, optional parameter, if passed and true, will force the new header to replace any other headers registered with that type.

2.4.5. Zend_Controller_Response_Cli

Zend_Controller_Response_Cli is a response object suitable for use in an CLI environment. It has no methods for handling headers, and simply returns all body content when __toString() is invoked.