Zend_Mvc-Routing.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<section 
    xmlns="http://docbook.org/ns/docbook" version="5.0"
    xml:id="zend.mvc.routing">
  <title>Routing</title>

  <para>
    Routing is the act of matching a request to a given controller.
  </para>

  <para>
    Typically, routing will examine the request URI, and attempt to
    match the URI path segment against provided constraints. If the
    constraints match, a set of "matches" are returned, one
    of which should be the controller name to execute. Routing can
    utilize other portions of the request URI or environment as well --
    for example, the host or scheme, query parametes, headers, request
    method, and more.
  </para>

  <para>
    Routing has been written from the ground up for Zend Framework 2.0.
    Execution is quite similar, but the internal workings are more
    consistent, performant, and often simpler.
  </para>

  <para>
    The base unit of routing is a <classname>Route</classname>:
  </para>

  <programlisting language="php"><![CDATA[
namespace Zend\Mvc\Router;

use zend\Stdlib\RequestInterface as Request;

interface Route
{
    public static function factory(array $options = array());
    public function match(Request $request);
    public function assemble(array $params = array(), array $options = array());
}
]]></programlisting>

  <para>
    A <classname>Route</classname> accepts a <classname>Request</classname>,
    and determines if it matches. If so, it returns a
    <classname>RouteMatch</classname> object:
  </para>

  <programlisting language="php"><![CDATA[
namespace Zend\Mvc\Router;

class RouteMatch
{
    public function __construct(array $params);
    public function setParam($name, $value);
    public function merge(RouteMatch $match);
    public function getParam($name, $default = null);
    public function getRoute();
}
]]></programlisting>

  <para>
    Typically, when a <classname>Route</classname> matches, it will define
    one or more parameters. These are passed into the
    <classname>RouteMatch</classname>, and objects may query the
    <classname>RouteMatch</classname> for their values.
  </para>

  <programlisting language="php"><![CDATA[
$id = $routeMatch->getParam('id', false);
if (!$id) {
    throw new Exception('Required identifier is missing!');
}
$entity = $resource->get($id);
]]></programlisting>

  <para>
    Usually you will have multiple routes you wish to test against. In
    order to facilitate this, you will use a route aggregate, usually
    implementing <classname>RouteStack</classname>:
  </para>

  <programlisting language="php"><![CDATA[
namespace Zend\Mvc\Router;

interface RouteStack extends Route
{
    public function addRoute($name, $route, $priority = null);
    public function addRoutes(array $routes);
    public function removeRoute($name);
}
]]></programlisting>

  <para>
    Typically, routes should be queried in a LIFO order, and hence the
    reason behind the name <classname>RouteStack</classname>. Zend
    Framework provides two implementations of this interface,
    <classname>SimpleRouteStack</classname> and
    <classname>TreeRouteStack</classname>. In each, you register routes
    either one at a time using <methodname>addRoute()</methodname>, or in
    bulk using <methodname>addRoutes()</methodname>.
  </para>

  <programlisting language="php"><![CDATA[
// One at a time:
$route = Literal::factory(array(
    'route' => '/foo',
    'defaults' => array(
        'controller' => 'foo-index',
        'action'     => 'index',
    ),
));
$router->addRoute('foo', $route);

$router->addRoutes(array(
    // using already instantiated routes:
    'foo' => $route,

    // providing configuration to allow lazy-loading routes:
    'bar' => array(
        'type' => 'literal',
        'options' => array(
            'route' => '/bar',
            'defaults' => array(
                'controller' => 'bar-index',
                'action'     => 'index',
            ),
        ),
    ),
));
]]></programlisting>

  <section xml:id="zend.mvc.routing.router-types">
    <title>Router Types</title>

    <para>
      Two routers are provided, the <classname>SimpleRouteStack</classname>
      and <classname>TreeRouteStack</classname>. Each works with the above
      interface, but utilize slightly different options and execution
      paths.
    </para>

    <section xml:id="zend.mvc.routing.router-types.simple-route-stack">
      <title>SimpleRouteStack</title>

      <para>
        This router simply takes individual routes that provide their full
        matching logic in one go, and loops through them in LIFO order
        until a match is found. As such, routes that will match most often
        should be registered last, and least common routes first.
        Additionally, you will need to ensure that routes that potentially
        overlap are registered such that the most specific match will match
        first (i.e., register later). Alternatively, you can set priorities by
        giving the priority as third parameter to the
        <methodname>addRoute()</methodname> method, specifying the priority
        in the route specifications or setting the priority property within
        a route instance before adding it to the route stack.
      </para>
    </section>

    <section xml:id="zend.mvc.routing.router-types.tree-route-stack">
      <title>TreeRouteStack</title>

      <para>
        <classname>Zend\Mvc\Router\Http\TreeRouteStack</classname> provides the
        ability to register trees of routes, and will use a B-tree
        algorithm to match routes. As such, you register a single route
        with many children.
      </para>

      <para>
        A <classname>TreeRouteStack</classname> will consist of the following
        configuration:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            A base "route", which describes the base match needed,
            the root of the tree.
          </para>
        </listitem>

        <listitem>
          <para>
            An optional "route_broker", which is a configured
            <classname>Zend\Mvc\Router\RouteBroker</classname> that can lazy-load
            routes.
          </para>
        </listitem>

        <listitem>
          <para>
            The option "may_terminate", which hints to the router
            that no other segments will follow it.
          </para>
        </listitem>

        <listitem>
          <para>
            An optional "child_routes" array, which contains
            additional routes that stem from the base "route" (i.e.,
            build from it). Each child route can itself be a
            <classname>TreeRouteStack</classname> if desired; in fact, the
            <classname>Part</classname> route works exactly this way.
          </para>
        </listitem>
      </itemizedlist>

      <para>
        When a route matches against a <classname>TreeRouteStack</classname>,
        the matched parameters from each segment of the tree will be
        returned.
      </para>

      <para>
        A <classname>TreeRouteStack</classname> can be your sole route for your
        application, or describe particular path segments of the
        application.
      </para>

      <para>
        An example of a <classname>TreeRouteStack</classname> is provided in
        the documentation of the <classname>Part</classname> route.
      </para>
    </section>
  </section>

  <section xml:id="zend.mvc.routing.route-types">
    <title>Route Types</title>

    <para>
      Zend Framework 2.0 ships with the following route types.
    </para>

    <section xml:id="zend.mvc.routing.route-types.hostname">
      <title>Zend\Mvc\Router\Http\Hostname</title>

      <para>
        The <classname>Hostname</classname> route attempts to match the
        hostname registered in the request against specific criteria.
        Typically, this will be in one of the following forms:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            "subdomain.domain.tld"
          </para>
        </listitem>

        <listitem>
          <para>
            ":subdomain.domain.tld"
          </para>
        </listitem>
      </itemizedlist>

      <para>
        In the above, the second route would return a "subdomain"
        key as part of the route match.
      </para>

      <para>
        For any given hostname segment, you may also provide a constraint.
        As an example, if the "subdomain" segment needed to match
        only if it started with "fw" and contained exactly 2
        digits following, the following route would be needed:
      </para>

      <programlisting language="php"><![CDATA[
$route = Hostname::factory(array(
    'route' => ':subdomain.domain.tld',
    'constraints' => array(
        'subdomain' => 'fw\d{2}'
    ),
));
]]></programlisting>

      <para>
        In the above example, only a "subdomain" key will be
        returned in the <classname>RouteMatch</classname>. If you wanted to
        also provide other information based on matching, or a default
        value to return for the subdomain, you need to also provide
        defaults.
      </para>

      <programlisting language="php"><![CDATA[
$route = Hostname::factory(array(
    'route' => ':subdomain.domain.tld',
    'constraints' => array(
        'subdomain' => 'fw\d{2}'
    ),
    'defaults' => array(
        'type' => 'json',
    ),
));
]]></programlisting>

      <para>
        When matched, the above will return two keys in the
        <classname>RouteMatch</classname>, "subdomain" and
        "type".
      </para>
    </section>

    <section xml:id="zend.mvc.routing.route-types.literal">
      <title>Zend\Mvc\Router\Http\Literal</title>

      <para>
        The <classname>Literal</classname> route is for doing exact matching of
        the URI path. Configuration therefore is solely the path you want
        to match, and the "defaults", or parameters you want
        returned on a match.
      </para>

      <programlisting language="php"><![CDATA[
$route = Literal::factory(array(
    'route' => '/foo',
    'defaults' => array(
        'controller' => 'foo-index',
    ),
));
]]></programlisting>

      <para>
        The above route would match a path "/foo", and return the
        key "controller" in the <classname>RouteMatch</classname>,
        with the value "foo-index".
      </para>
    </section>

    <section xml:id="zend.mvc.routing.route-types.part">
      <title>Zend\Mvc\Router\Http\Part</title>

      <para>
        A <classname>Part</classname> route allows crafting a tree of possible
        routes based on segments of the URI path. It actually extends the
        <classname>TreeRouteStack</classname>.
      </para>

      <para>
        <classname>Part</classname> routes are difficult to describe, so we'll
        simply provide a sample one here.
      </para>

      <programlisting language="php"><![CDATA[
$route = Part::factory(array(
    'route' => array(
        'type'    => 'literal',
        'options' => array(
            'route'    => '/',
            'defaults' => array(
                'controller' => 'ItsHomePage',
            ),
        )
    ),
    'may_terminate' => true,
    'route_broker'  => $routeBroker,
    'child_routes'  => array(
        'blog' => array(
            'type'    => 'literal',
            'options' => array(
                'route'    => 'blog',
                'defaults' => array(
                    'controller' => 'ItsBlog',
                ),
            ),
            'may_terminate' => true,
            'child_routes'  => array(
                'rss' => array(
                    'type'    => 'literal',
                    'options' => array(
                        'route'    => '/rss',
                        'defaults' => array(
                            'controller' => 'ItsRssBlog',
                        ),
                    ),
                    'child_routes'  => array(
                        'sub' => array(
                            'type'    => 'literal',
                            'options' => array(
                                'route'    => '/sub',
                                'defaults' => array(
                                    'action' => 'ItsSubRss',
                                ),
                            )
                        ),
                    ),
                ),
            ),
        ),
        'forum' => array(
            'type'    => 'literal',
            'options' => array(
                'route'    => 'forum',
                'defaults' => array(
                    'controller' => 'ItsForum',
                ),
            ),
        ),
    ),
));
]]></programlisting>

      <para>
        The above would match the following:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            "/" would load the "ItsHomePage" controller
          </para>
        </listitem>

        <listitem>
          <para>
            "/blog" would load the "ItsBlog" controller
          </para>
        </listitem>

        <listitem>
          <para>
            "/blog/rss" would load the "ItsRssBlog"
            controller
          </para>
        </listitem>

        <listitem>
          <para>
            "/blog/rss/sub" would load the "ItsSubRss"
            controller
          </para>
        </listitem>

        <listitem>
          <para>
            "/forum" would load the "ItsForum" controller
          </para>
        </listitem>
      </itemizedlist>

      <para>
        You may use any route type as a child route of a
        <classname>Part</classname> route.
      </para>
    </section>

    <section xml:id="zend.mvc.routing.route-types.regex">
      <title>Zend\Mvc\Router\Http\Regex</title>

      <para>
        A <classname>Regex</classname> route utilizes a regular expression to
        match against the URI path. Any valid regular expession is allowed;
        our recommendation is to use named captures for any values you want
        to return in the <classname>RouteMatch</classname>.
      </para>

      <para>
        Since regular expression routes are often complex, you must specify
        a "spec" or specification to use when assembling URLs
        from regex routes. The spec is simply a string; replacements are
        identified using "%keyname%" within the string, with the
        keys coming from either the captured values or named parameters
        passed to the <methodname>assemble()</methodname> method.
      </para>

      <para>
        Just like other routes, the <classname>Regex</classname> route can
        accept "defaults", parameters to include in the
        <classname>RouteMatch</classname> when succesfully matched.
      </para>

      <programlisting language="php"><![CDATA[
$route = Regex::factory(array(
    'regex' => '/blog/(?<id>[a-zA-Z0-9_-]+)(\.(?<format>(json|html|xml|rss)))?',
    'defaults' => array(
        'controller' => 'blog-entry',
        'format'     => 'html',
    ),
    'spec' => '/blog/%id%.%format%',
));
]]></programlisting>

      <para>
        The above would match
        "/blog/001-some-blog_slug-here.html", and return three
        items in the <classname>RouteMatch</classname>, an "id", the
        "controller", and the "format". When assembling
        a URL from this route, the "id" and "format"
        values would be used to fill the specification.
      </para>
    </section>

    <section xml:id="zend.mvc.routing.route-types.scheme">
      <title>Zend\Mvc\Router\Http\Scheme</title>

      <para>
        The <classname>Scheme</classname> route matches the URI scheme only,
        and must be an exact match. As such, this route, like the
        <classname>Literal</classname> route, simply takes what you want to
        match and the "defaults", parameters to return on a
        match.
      </para>

      <programlisting language="php"><![CDATA[
$route = Scheme::factory(array(
    'scheme' => 'https',
    'defaults' => array(
        'https' => true,
    ),
));
]]></programlisting>

      <para>
        The above route would match the "https" scheme, and
        return the key "https" in the
        <classname>RouteMatch</classname> with a boolean
        <varname>true</varname> value.
      </para>
    </section>

    <section xml:id="zend.mvc.routing.route-types.segment">
      <title>Zend\Mvc\Router\Http\Segment</title>

      <para>
        A <classname>Segment</classname> route allows matching any segment of a
        URI path. Segments are denoted using a colon, followed by
        alphanumeric characters; if a segment is optional, it should be
        surrounded by brackets. As an example, "/:foo[/:bar]"
        would match a "/" followed by text and assign it to the
        key "foo"; if any additional "/" characters are
        found, any text following the last one will be assigned to the key
        "bar".
      </para>

      <para>
        The separation between literal and named segments can be anything.
        For example, the above could be done as "/:foo{-}[-:bar] as well. The
        {-} after the :foo parameter indicates a set of one or more delimiters,
        after which matching of the parameter itself ends.
      </para>

      <para>
        Each segment may have constraints associated with it. Each
        constraint should simply be a regular expression expressing the
        conditions under which that segment should match.
      </para>

      <para>
        Also, as you can in other routes, you may provide defaults to use;
        these are particularly useful when using optional segments.
      </para>

      <para>
        As a complex example:
      </para>

      <programlisting language="php"><![CDATA[
$route = Segment::factory(array(
    'route' => '/:controller[/:action]',
    'constraints' => array(
        'controller' => '[a-zA-Z][a-zA-Z0-9_-]+',
        'action'     => '[a-zA-Z][a-zA-Z0-9_-]+',
    ),
    'defaults' => array(
        'controller' => 'application-index',
        'action'     => 'index',
    ),
));
]]></programlisting>
    </section>
  </section>
</section>