<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<phpdoc:classref xml:id="class.yaf-router" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>The Yaf_Router class</title>
 <titleabbrev>Yaf_Router</titleabbrev>

 <partintro>

<!-- {{{ Yaf_Router intro -->
  <section xml:id="yaf-router.intro">
   &reftitle.intro;
   <para>
   <classname>Yaf_Router</classname> is the standard framework router. Routing is
   the process of taking a URI endpoint (that part of the URI which comes
   after the base URI: see <methodname>Yaf_Request_Abstract::setBaseUri</methodname>)
   and decomposing it into parameters to determine which module, controller, and
   action of that controller should receive the request. This values of the module,
   controller, action and other parameters are packaged into a
   <classname>Yaf_Request_Abstract</classname> object which is then processed by
   <classname>Yaf_Dispatcher</classname>. Routing occurs only once: when the request
   is initially received and before the first controller is dispatched.

   <classname>Yaf_Router</classname> 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 Apache mod_rewrite rule
   (one of):
   <example>
    <title>Rewrite rule for Apache</title>
   <programlisting role="conf">
<![CDATA[
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
]]>
   </programlisting>
   </example>
   or (preferred):
   <example>
   <title>Rewrite rule for Apache</title>
   <programlisting role="conf">
<![CDATA[
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
]]>
   </programlisting>
  </example>
   If using Lighttpd, the following rewrite rule is valid:
   <example>
    <title>Rewrite rule for Lighttpd</title>
   <programlisting role="conf">
<![CDATA[
url.rewrite-once = (
  ".*\?(.*)$" => "/index.php?$1",
  ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
  "" => "/index.php"
)
]]>
   </programlisting>
  </example>
   If using Nginx, use the following rewrite rule:
   <example>
    <title>Rewrite rule for Nginx</title>
   <programlisting role="conf">
<![CDATA[
server {
  listen ****;
  server_name  yourdomain.com;
  root   document_root;
  index  index.php index.html;

  if (!-e $request_filename) {
    rewrite ^/(.*)  /index.php/$1 last;
  }
}
]]>
   </programlisting>
  </example>
   </para>
  </section>
<!-- }}} -->

  <section xml:id="yaf-router.default">
   <title>Default route</title>
   <para>
    <classname>Yaf_Router</classname> comes preconfigured with a default route
    <classname>Yaf_Route_Static</classname>, which will match URIs in the shape of 
    controller/action. Additionally, a module name may be specified as the first
    path element, allowing URIs of the form module/controller/action. Finally, 
    it will also match any additional parameters appended to the URI by default 
    - controller/action/var1/value1/var2/value2.
    <note>
     <para>
      Module name must be defined in config, considering application.module="Index,Foo,Bar",
      in this case, only index, foo and bar can be considered as a module name.
      if doesn't config, there is only one module named "Index". 
     </para>
    </note>
   </para>

   <para>
   Some examples of how such routes are matched:
   <example>
    <title><classname>Yaf_Route_Static</classname>(default route)example</title>
   <programlisting role="conf">
<![CDATA[
// Assuming the following configure:
$conf = array(
   "application" => array(
      "modules" => "Index,Blog",
   ),
);

Controller only:
http://example/news
    controller == news
Action only(when defined yaf.action_prefer=1 in php.ini)
    action  == news
 
Invalid module maps to controller name:
http://example/foo
    controller == foo
 
Module + controller:
http://example/blog/archive
    module     == blog
    controller == archive
 
Module + controller + action:
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list
 
Module + controller + action + params:
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc
]]>
   </programlisting>
  </example>

  </para>
  </section>

  <section xml:id="yaf-router.synopsis">
   &reftitle.classsynopsis;

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>Yaf_Router</classname></ooclass>

<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <classname>Yaf_Router</classname>
     </ooclass>
    </classsynopsisinfo>
<!-- }}} -->
    <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>protected</modifier>
     <varname linkend="yaf-router.props.routes">_routes</varname>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>protected</modifier>
     <varname linkend="yaf-router.props.current">_current</varname>
    </fieldsynopsis>

    
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.yaf-router')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])" />
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.yaf-router')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
   </classsynopsis>
<!-- }}} -->

  </section>

  
<!-- {{{ Yaf_Router properties -->
  <section xml:id="yaf-router.props">
   &reftitle.properties;
   <variablelist>
    <varlistentry xml:id="yaf-router.props.routes">
     <term><varname>_routes</varname></term>
     <listitem>
      <para>
      registered routes stack
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="yaf-router.props.current">
     <term><varname>_current</varname></term>
     <listitem>
      <para>
       after routing phase, this indicated the name of which route
       is used to route current request.

       you can get this name by
       <methodname>Yaf_Router::getCurrentRoute</methodname>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
<!-- }}} -->


 </partintro>

 &reference.yaf.entities.yaf-router;

</phpdoc:classref>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
