From 35d4da3258c94bbde2effe50a18b9fc54056694d Mon Sep 17 00:00:00 2001 From: Xinchen Hui Date: Fri, 22 Feb 2013 08:52:49 +0000 Subject: [PATCH] Update docs for router git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329534 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/yaf/yaf-controller-abstract.xml | 23 ++++++++--- reference/yaf/yaf-route-map.xml | 15 +++++++ reference/yaf/yaf-route-static.xml | 6 +-- reference/yaf/yaf-router.xml | 41 +++++++++++-------- .../yaf/yaf_request_abstract/setbaseuri.xml | 20 ++++++--- 5 files changed, 73 insertions(+), 32 deletions(-) diff --git a/reference/yaf/yaf-controller-abstract.xml b/reference/yaf/yaf-controller-abstract.xml index 8c36338639..931152fc8c 100644 --- a/reference/yaf/yaf-controller-abstract.xml +++ b/reference/yaf/yaf-controller-abstract.xml @@ -23,7 +23,7 @@ You will find that you can not define __construct function for your custom controller, thus, Yaf_Controller_Abstract provides - a magic method: Yaf_Controller_Abstract::init(). + a magic method: Yaf_Controller_Abstract::init. If you have defined a init() method in your custom controller, it will be @@ -33,8 +33,14 @@ Action may have arguments, when a request coming, if there are the same name variable in the request parameters(see Yaf_Request_Abstract::getParam) after routed, - Yaf will pass them to the action method(see - Yaf_Action_Abstract::execute). + Yaf will pass them to the action method + (see Yaf_Action_Abstract::execute). + + + These arguments are directly fetched without filtering, it should be + carefully processed before use them. + + @@ -116,6 +122,7 @@ class IndexController extends Yaf_Controller_Abstract { /* action method may have arguments */ public indexAction($name, $id) { + /* $name and $id are unsafe raw data */ assert($name == $this->getRequest()->getParam("name")); assert($id == $this->_request->getParam("id")); } @@ -152,21 +159,25 @@ class DummyAction extends Yaf_Action_Abstract { _name - + + controller name + _request - the request object + current request object _response - + + current response object + diff --git a/reference/yaf/yaf-route-map.xml b/reference/yaf/yaf-route-map.xml index 0bcd8490cf..bb4fbc53ea 100644 --- a/reference/yaf/yaf-route-map.xml +++ b/reference/yaf/yaf-route-map.xml @@ -12,7 +12,22 @@
&reftitle.intro; + Yaf_Route_Map is a built-in route, it simply + convert a URI endpoint (that part of the URI which comes after the + base URI: see Yaf_Request_Abstract::setBaseUri) + to a controller name or action name(depends on the paramter passed to + Yaf_Route_Map::__construct) in following rule: + A => controller A. + A/B/C => controller A_B_C. + A/B/C/D/E => controller A_B_C_D_E. + + + If the second parameter of + Yaf_Route_Map::__construct is specificed, then + only the part before delimeter of URI will used to routing, the part after + it is used to routing request parameters (see the example section of + Yaf_Route_Map::__construct).
diff --git a/reference/yaf/yaf-route-static.xml b/reference/yaf/yaf-route-static.xml index e64442a7cf..8f3fa12ede 100644 --- a/reference/yaf/yaf-route-static.xml +++ b/reference/yaf/yaf-route-static.xml @@ -21,9 +21,9 @@ please *NOTE* that it is unecessary to instance a Yaf_Route_Static, also - unecesary to add it into Yaf_Router's route stack, - since there is always be one in Yaf_Router's route - stack, and always be called at the last time. + unecesary to add it into Yaf_Router's routes stack, + since there is always be one in Yaf_Router's + routes stack, and always be called at the last time. diff --git a/reference/yaf/yaf-router.xml b/reference/yaf/yaf-router.xml index 39be288dbc..eb705f0d9d 100644 --- a/reference/yaf/yaf-router.xml +++ b/reference/yaf/yaf-router.xml @@ -14,13 +14,13 @@ Yaf_Router 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 Yaf_Request_Abstract object which is then - processed by Yaf_Dispatcher. Routing occurs only once: - when the request is initially received and before the first controller is - dispatched. + after the base URI: see Yaf_Request_Abstract::setBaseUri) + 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 + Yaf_Request_Abstract object which is then processed by + Yaf_Dispatcher. Routing occurs only once: when the request + is initially received and before the first controller is dispatched. Yaf_Router is designed to allow for mod_rewrite-like functionality using pure PHP structures. It is very loosely based on Ruby @@ -88,12 +88,12 @@ server {
Default route - 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. + Yaf_Router comes preconfigured with a default route + Yaf_Route_Static, 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. Module name must be defined in config, considering application.module="Index,Foo,Bar", @@ -106,8 +106,7 @@ server { Some examples of how such routes are matched: - <classname>Yaf_Route_Static</classname>(default - route)example + <classname>Yaf_Route_Static</classname>(default route)example _routes - + + registered routes stack + _current - + + after routing phase, this indicated the name of which route + is used to route current request. + + you can get this name by + Yaf_Router::getCurrentRoute. + diff --git a/reference/yaf/yaf_request_abstract/setbaseuri.xml b/reference/yaf/yaf_request_abstract/setbaseuri.xml index d802b6d559..b6b8ab257f 100644 --- a/reference/yaf/yaf_request_abstract/setbaseuri.xml +++ b/reference/yaf/yaf_request_abstract/setbaseuri.xml @@ -4,21 +4,29 @@ Yaf_Request_Abstract::setBaseUri - The setBaseUri purpose + set base URI &reftitle.description; - public voidYaf_Request_Abstract::setBaseUri + public boolYaf_Request_Abstract::setBaseUri stringuir + Set base URI, base URI is used when doing routing, in routing phase request + URI is used to route a request, while base URI is used to skip the + leadding part(base URI) of request URI. + That is, if comes a request with request URI a/b/c, then if you set base + URI to "a/b", only "/c" will be used in routing phase. + + + generally, you don't need to set this, Yaf will determine it automatically. + + - &warn.undocumented.func; - @@ -28,7 +36,7 @@ uir - + base URI @@ -38,7 +46,7 @@ &reftitle.returnvalues; - + bool