When a site user enters a URL in a web browser, the request is finally dispatched to controller’s action. ZF2-based application maps page URLs to controllers and their actions. This mapping is accomplished with the help of routing. Routing is implemented as a part of
To better understand routing, we first need to look at the URL structure. A typical URL from an HTTP request consists of segments. The segments are URL parts delimited by slash characters (‘/’): there are scheme, host name, path and query segments.
For example, let’s look at the URL http://site1.yourserver.com/path/to/page?query=Search
This URL begins with a scheme segment (the scheme typically looks like http or https). Then, the host name segment follows which is the domain name of your web server (like site1.yourserver.com). Optional path segments follow the host name. So if you have the path part “/path/to/page” then “path”, “to”, and “page” would each be a URL segment. Next, after the question mark, the optional query part follows. It consists of one or several “name=value” parameters separated from each other by an ampersand character (‘&’).
Each segment in a URL uses special character encoding, which is named the URL encoding. This encoding ensures that the URL contains only “safe” characters from the ASCII table. If a URL contains unsafe characters, they are replaced with a percentage character (‘%’) followed by two hexadecimal digits (for example, the space character will be replaced by ‘%20’).
Routing is a mechanism which allows to map HTTP request to the controller.
With routing, ZF2 knows which of the controller’s action method to execute
as the result of the request. For example, you can map http://localhost/ URL to
IndexController::indexAction() method or http://localhost/about URL to
A typical routing rule has the name, type and options. The name is used to uniquely identify the rule. The type defines the name of the PHP class which implements the algorithm used for comparing the URL string. The options is an array that includes the route string which should be compared against the URL string, and several parameters called the defaults.
In general, the routing algorithm may use any data from HTTP request for matching the route. However, typically, it takes only the URL string (or its substring) as input. The algorithm then compares the URL with the route, and if the URL string matches the route, returns several parameters, including the controller’s name and action method’s name, and possibly others. These parameters may be either hard-coded in a configuration file or grabbed from the URL string. If a certain parameter cannot be retrieved from the URL, its default value is returned.
There are several standard route types provided by Zend Framework 2. These route types are implemented as classes living in the
- Literal Exact matching against a path part of a URL.
- Segment Matching against a path segment (or several segments) of a URL.
- Regex Matching the path part of a URL against a regular expression template.
- Wildcard Matching the path part of a URL against a key/value pattern.
Hostname Matching the host name against some criteria.
- Scheme Matching URL scheme against some criteria.
- Method Matching an HTTP method (e.g. GET, POST, etc.) against some criteria.
Each route type above (except the Method type) may be matched against a specific segment (or several segments) of a URL. The Method route type is matched against the HTTP method (either GET or POST) retrieved from HTTP request.
There is also the Query route type, which is declared deprecated and is not
recommended to use. This route type is actually not needed, because you can
retrieve query parameters from your URL with the
Params controller plugin.
As an example of route definition, let’s consider the Literal route type.
Literal Route Type
With Literal route type, the route match is achieved only when you have the
exact literal match of the route string against the URL path. You typically use the Literal type for URLs which should be short and memorable, like ‘/about’ or ‘/news’.
Below, the definition of the route named “home” is presented. The “home” route is
usually mapped to the “index” action of the
IndexController and points to the Home page of your site:
'home' => array( 'type' => 'Zend\Mvc\Router\Http\Literal', 'options' => array( 'route' => '/', 'defaults' => array( 'controller' => 'Application\Controller\Index', 'action' => 'index', ), ), ),
Line 2 of this example says that the route’s type is Literal. The actual
route matching algorithm is implemented in the
class. You can either specify the full class name or its short alias (
Line 4 defines the route string to match against the URL path (the forward slash ‘/’ means the empty URL part). Because we have the literal route type, the route match is achieved only when you have the exact literal path match. For example, if you have the URL http://localhost/ or http://localhost, it will match the ‘/’ route string.
Lines 5-8 define the
defaults, which are the parameters returned by the router
if the route matches. The
action parameters define the controller and controller’s action method which should be executed. You can also define other parameters here, if needed.
Note: this post is an excerpt from Chapter 5 “URL Routing” of my book Using Zend Framework 2.