php-doc-en/reference/yaf/yaf-router.xml

<?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 URL) 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>
   Yaf_Router comes preconfigured with a default route, 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 considerd 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: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></para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="yaf-router.props.current">
     <term><varname>_current</varname></term>
     <listitem>
      <para></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
-->