From 702e372f6cc608578f1c3de513df94174e64bf48 Mon Sep 17 00:00:00 2001
From: Xinchen Hui <laruence@php.net>
Date: Mon, 28 Nov 2011 04:55:20 +0000
Subject: [PATCH] update docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@320070 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/yaf/yaf-route-regex.xml             |   3 +-
 reference/yaf/yaf_route_regex/construct.xml   |  81 ++++++++++++-
 reference/yaf/yaf_route_rewrite/construct.xml | 112 +++++++++++++++++-
 3 files changed, 189 insertions(+), 7 deletions(-)

diff --git a/reference/yaf/yaf-route-regex.xml b/reference/yaf/yaf-route-regex.xml
index be543541a8..6f401da6fa 100644
--- a/reference/yaf/yaf-route-regex.xml
+++ b/reference/yaf/yaf-route-regex.xml
@@ -12,7 +12,8 @@
   <section xml:id="yaf-route-regex.intro">
    &reftitle.intro;
    <para>
-
+     <classname>Yaf_Route_Regex</classname> is the most flexible route among
+     the Yaf built-in routes.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/yaf/yaf_route_regex/construct.xml b/reference/yaf/yaf_route_regex/construct.xml
index e3e03f3de7..df4392ee65 100644
--- a/reference/yaf/yaf_route_regex/construct.xml
+++ b/reference/yaf/yaf_route_regex/construct.xml
@@ -17,7 +17,7 @@
    <methodparam choice="opt"><type>array</type><parameter>verify</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+    
   </para>
 
   &warn.undocumented.func;
@@ -31,7 +31,9 @@
     <term><parameter>match</parameter></term>
     <listitem>
      <para>
-      
+       A complete Regex pattern, will be used to match a request uri, if
+       doesn't matched, <classname>Yaf_Route_Regex</classname> will return
+       FALSE.
      </para>
     </listitem>
    </varlistentry>
@@ -39,7 +41,13 @@
     <term><parameter>route</parameter></term>
     <listitem>
      <para>
-      
+      When the match pattern matches the request uri,
+      <classname>Yaf_Route_Regex</classname> will use this to decide which
+      m/c/a to routed.
+     </para>
+     <para>
+      either of m/c/a in this array is optianl, if you don't assgian a
+      specific value, it will be routed to default.
      </para>
     </listitem>
    </varlistentry>
@@ -47,7 +55,7 @@
     <term><parameter>map</parameter></term>
     <listitem>
      <para>
-      
+      A array to assign name to the captrues in the match result.
      </para>
     </listitem>
    </varlistentry>
@@ -69,6 +77,71 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>Yaf_Route_Regex</function>example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+   /**
+    * Add a regex route to Yaf_Router route stack
+    */
+    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
+        new Yaf_Route_Regex(
+           "#^/product/([^/]+)/([^/])+#", //match request uri leading "/product"
+           array(
+               'controller' => "product",  //route to product controller,
+           ),
+           array(
+              1 => "name",   // now you can call $request->getParam("name")
+              2 => "id",     // to get the first captrue in the match pattern.
+           )
+        )
+    );
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title><function>Yaf_Route_Regex</function>example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+   /**
+    * Add a regex route to Yaf_Router route stack by calling addconfig
+    */
+    $config = array(
+        "name" => array(
+           "type"  => "regex",          //Yaf_Route_Regex route
+           "match" => "#(.*)#",         //match arbitrary request uri
+           "route" => array(
+               'controller' => "product",  //route to product controller,
+               'action'     => "dummy",    //route to dummy action
+           ),
+           "map" => array(
+              1 => "uri",   // now you can call $request->getParam("uri")
+           ),
+        ),
+    );
+    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
+        new Yaf_Config_Simple($config));
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Yaf_Router::addRoute</methodname></member>
+   <member><methodname>Yaf_Router::addConfig</methodname></member>
+   <member><classname>Yaf_Route_Static</classname></member>
+   <member><classname>Yaf_Route_Supervar</classname></member>
+   <member><classname>Yaf_Route_Simple</classname></member>
+   <member><classname>Yaf_Route_Rewrite</classname></member>
+   <member><classname>Yaf_Route_Map</classname></member>
+  </simplelist>                       
+ </refsect1>  
 
 </refentry>
 
diff --git a/reference/yaf/yaf_route_rewrite/construct.xml b/reference/yaf/yaf_route_rewrite/construct.xml
index 4dc7284c53..e53d6148d8 100644
--- a/reference/yaf/yaf_route_rewrite/construct.xml
+++ b/reference/yaf/yaf_route_rewrite/construct.xml
@@ -30,7 +30,9 @@
     <term><parameter>match</parameter></term>
     <listitem>
      <para>
-      
+       A pattern, will be used to match a request uri, if
+       doesn't matched, <classname>Yaf_Route_Rewrite</classname> will return
+       FALSE.
      </para>
     </listitem>
    </varlistentry>
@@ -38,7 +40,13 @@
     <term><parameter>route</parameter></term>
     <listitem>
      <para>
-      
+      When the match pattern matches the request uri,
+      <classname>Yaf_Route_Rewrite</classname> will use this to decide which
+      m/c/a to routed.
+     </para>
+     <para>
+      either of m/c/a in this array is optianl, if you don't assgian a
+      specific value, it will be routed to default.
      </para>
     </listitem>
    </varlistentry>
@@ -60,6 +68,106 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>Yaf_Route_Rewrite</function>example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+   /**
+    * Add a rewrite route to Yaf_Router route stack
+    */
+    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
+        new Yaf_Route_rewrite(
+           "/product/:name/:id/*", //match request uri leading "/product"
+           array(
+               'controller' => "product",  //route to product controller,
+           ),
+        )
+    );
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+/* for http://yourdomain.com/product/foo/22/foo/bar
+ * route will result in following values:
+ */
+array(
+  "controller" => "product",
+  "module"     => "index", //(default)
+  "action"     => "index", //(default)
+)
+
+/**
+ * and request parameters:
+ */
+array(
+  "name" => "foo",
+  "id"   => 22,
+  "foo"  => bar
+)
+]]>
+   </screen>
+  </example>
+  <example>
+   <title><function>Yaf_Route_Rewrite</function>example</title>
+   <programlisting role="php">
+<![CDATA[
+    <?php
+   /**
+    * Add a rewrite route to Yaf_Router route stack by calling addconfig
+    */
+    $config = array(
+        "name" => array(
+           "type"  => "rewrite",        //Yaf_Route_Rewrite route
+           "match" => "/user-list/:id", //match only /user/list/?/
+           "route" => array(
+               'controller' => "user",  //route to user controller,
+               'action'     => "list",  //route to list action
+           ),
+        ),
+    );
+    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
+        new Yaf_Config_Simple($config));
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+/* for http://yourdomain.com/user-list/22
+ * route will result in following values:
+ */
+array(
+  "controller" => "user",
+  "action"     => "list",
+  "module"     => "index", //(default)
+)
+
+/**
+ * and request parameters:
+ */
+array(
+  "id"   => 22,
+)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Yaf_Router::addRoute</methodname></member>
+   <member><methodname>Yaf_Router::addConfig</methodname></member>
+   <member><classname>Yaf_Route_Static</classname></member>
+   <member><classname>Yaf_Route_Supervar</classname></member>
+   <member><classname>Yaf_Route_Simple</classname></member>
+   <member><classname>Yaf_Route_Regex</classname></member>
+   <member><classname>Yaf_Route_Map</classname></member>
+  </simplelist>                       
+ </refsect1>  
 
 </refentry>