Changeset 161

Timestamp:

03/02/06 17:20:34 (6 years ago)

Author:

haas

Message:

Finish Router class doc, regression test

Location:

trunk/trax

Files:

• config/routes.php (modified) (1 diff)
• test/RouterTest.php (modified) (1 diff)
• tutorials/PHPonTrax/Router.cls (modified) (2 diffs)
• vendor/trax/action_controller.php (modified) (10 diffs)
• vendor/trax/router.php (modified) (7 diffs)

trunk/trax/config/routes.php

@@ -1 +1 @@
 <?php                       
 /**
+ *  Configuration file to define URL to action mapping
+ *
+ *  This file contains one or more PHP statements that call
+ *  {@link Router::connect() $router->connect()} to add routes to the
+ *  route table stored in the {@link Router} object pointed to by
+ *  $router.
+ *
  *  Add your own custom routes here.
  *  The priority is based upon order of creation: first created ->

trunk/trax/test/RouterTest.php

@@ -65 +65 @@
 
     /**
-     * @todo Implement testGet_selected_route().
+     *  Test build_route_regexp().
      */
-    public function testGet_selected_route() {
-        // Remove the following line when you implement this test.
-        throw new PHPUnit2_Framework_IncompleteTestError;
+    public function testBuild_route_regexp() {
+        $r = new Router;
+        // Two abstract route components
+        $regexp = $r->build_route_regexp(':foo/:bar');
+        $this->assertEquals($regexp,
+                            '^[a-z0-9_\-]+\/[a-z0-9_\-]+$');
+        // Three abstract route components
+        $regexp = $r->build_route_regexp(':foo/:bar/:mumble');
+        $this->assertEquals($regexp,
+                            '^[a-z0-9_\-]+\/[a-z0-9_\-]+\/[a-z0-9_\-]+$');
+        // Abstract, concrete, abstract route components
+        $regexp = $r->build_route_regexp(':foo/bar/:mumble');
+        $this->assertEquals($regexp,
+                            '^[a-z0-9_\-]+\/bar\/[a-z0-9_\-]+$');
+        // Two concrete route components
+        $regexp = $r->build_route_regexp('foo/bar');
+        $this->assertEquals($regexp,
+                            '^foo\/bar$');
     }
 
     /**
-     * @todo Implement testConnect().
+     * Test default route table
      */
-    public function testConnect() {
-        // Remove the following line when you implement this test.
-        throw new PHPUnit2_Framework_IncompleteTestError;
+    public function testDefault_route() {
+        $r = new Router;
+        // Should find default route
+        $route = $r->find_route('a/b/mumble');
+        $this->assertEquals(':controller/:action/:id', $route['path']);
+        $this->assertNull($route['params']);
     }
 
     /**
-     * @todo Implement testFind_route().
+     * Test route table with one simple entry besides default
      */
-    public function testFind_route() {
-        // Remove the following line when you implement this test.
-        throw new PHPUnit2_Framework_IncompleteTestError;
+    public function testSimple_route() {
+        $r = new Router;
+        //  Build route table
+        $r->connect(':foo/:bar/mumble', array('mumble route'));
+        //  Params not an array ignored, null is stored
+        $r->connect(':controller/:action/:id', 'not-an-array');
+
+        //  Match first route
+        $route = $r->find_route('a/b/mumble');
+        $this->assertEquals(':foo/:bar/mumble', $route['path']);
+        $this->assertEquals(array('mumble route'), $route['params']);
+        $selected = $r->get_selected_route();
+        $this->assertEquals(':foo/:bar/mumble', $selected['path']);
+        $this->assertEquals(array('mumble route'), $selected['params']);
+
+        //  Match second route
+        $route = $r->find_route('a/b/c');
+        $this->assertEquals(':controller/:action/:id', $route['path']);
+        $this->assertNull($route['params']);
+        $selected = $r->get_selected_route();
+        $this->assertEquals(':controller/:action/:id', $selected['path']);
+        $this->assertNull($selected['params']);
     }
 
     /**
-     * @todo Implement testBuild_route_regexp().
+     * Test route table with one regexp entry besides default
      */
-    public function testBuild_route_regexp() {
-        // Remove the following line when you implement this test.
-        throw new PHPUnit2_Framework_IncompleteTestError;
+    public function testRegexp_route() {
+        $r = new Router;
+        //  Build route table
+        $r->connect(':foo/:bar/\?(catalog|part)number=.*',
+                    array('number route'));
+        $r->connect(':controller/:action/:id', array('default route'));
+
+        //  Match first route
+        $route = $r->find_route('a/b/?catalognumber=17');
+        $this->assertEquals(':foo/:bar/\?(catalog|part)number=.*',
+                            $route['path']);
+        $this->assertEquals(array('number route'), $route['params']);
+        $route = $r->find_route('a/b/?partnumber=123-456');
+        $this->assertEquals(':foo/:bar/\?(catalog|part)number=.*',
+                            $route['path']);
+        $this->assertEquals(array('number route'), $route['params']);
+        $route = $r->find_route('a/b/?personnumber=156');
+        $this->assertEquals(':controller/:action/:id', $route['path']);
+        $this->assertEquals(array('default route'), $route['params']);
+    }
+
+    /**
+     * Test route table with route with empty path
+     */
+    public function testEmpty_route() {
+        $r = new Router;
+        //  Build route table with only an empty path
+        $r->connect('', array('empty route'));
+        $route = $r->find_route('');
+        $this->assertEquals('', $route['path']);
+        $this->assertEquals(array('empty route'), $route['params']);
+        //  This route shouldn't match anything
+        $route = $r->find_route('mumble/foo');
+        $this->assertNull($route);
     }
 }

trunk/trax/tutorials/PHPonTrax/Router.cls

@@ -2 +2 @@
  <refnamediv>
   <refname>Router</refname>
-  <refpurpose>@todo Router tutorial</refpurpose>
+  <refpurpose>Convert a URL to an action</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
@@ -15 +15 @@
  <refsect1 id="{@id intro}">
   <title>Introduction</title>
+
+  <para>The {@link Router Router class} owns the information and
+   algorithms that convert URLs to actions.  An object of this class
+   holds a {@link Router::$routes route table} containing routes to be
+   matched to URLs.</para>
+
+  <para>In normal operation, a Router object is created by 
+   {@link ActionController::load_router()} which reads routes from the
+   configuration file {@link routes.php config/routes.php}.</para>
+
  </refsect1>
+ <refsect1 id="{@id table}">
+  <title>Structure of the Route Table</title>
+
+  <para>The route table is an ordered list of routes.  A route consists
+   of a path and a (possibly null) parameter array. The structure of
+   the table is:</para>
+
+  <example>
+$routes[0]['path']    First route path
+          ['params']  First route parameters
+       [1]['path']    Second route path
+          ['params']  Second route parameters
+...
+  </example>
+
+  <para>A route path consists of character strings separated by
+   forward slash ('/') characters.  The route path must not begin
+   or end with '/', and the character strings in the path must
+   not contain '/'.  There are two kinds of character strings in
+   route paths:</para>
+
+  <unorderedlist>
+   <listitem>Placeholder strings start with a colon (':') followed by
+    one or more alphameric characters chosen from "a..z0..9_-".  A
+    placeholder string matches any alphameric string in the same
+    position of a URL.  The actual contents of the placeholder string
+    following ':' are irrelevant.</listitem> 
+   <listitem>Pattern strings start with any character except ':' or
+    '/' followed by any character except '/'.  The contents of
+    the pattern string are a
+    {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}.
+   </listitem>
+  </unorderedlist>
+
+  <para>The order of routes in the table is significant.  When a URL
+   is to be matched, the route table is searched in order from first
+   entry to last.  The first route entry that matches is
+   returned.</para>
+
+  <para>{@link Router::find_route()} guarantees that there will always be
+   at least one route in the table by inserting
+   {@link Router::$default_route_path} if the table is empty when
+   find_route() is called.</para>
+ </refsect1>
+
+ <refsect1 id="{@id build}">
+  <title>Constructing the Route Table</title>
+
+  <para>To construct a route table, first create a new Router object,
+   then  make multiple calls to {@link Router::connect()} to add route
+   entries to the object's table.  The second argument to connect(), if
+   specified, must be an array, but the array can hold anything (or
+   nothing).</para>
+
+  <para>There is no way to change or delete an existing route table
+   entry.</para>
+  <para>Either assure that any path you search for will return some
+  route, or prepare to deal with a null return from
+  {@link Router::find_route()} </para>
+
+  <para><important>CAUTION:</important> Do not call
+   {@link Router::find_route()} before calling
+   {@link Router::connect()}, unless you want the default route to be
+   the first entry in the route table.</para>
+
+ </refsect1>
+ <refsect1 id="{@id search}">
+  <title>Searching the Route Table</title>
+
+  <para>To look up a URL in the route table, call
+   {@link Router::find_route()} with the URL as argument.  A copy of
+   the first matching route table entry, if any, will be returned.  If
+   none matches, null will be returned.</para>
+
+  <para>A URL consisting of a null string '' matches a route
+   whose path is a null string.</para>
+
+  <para>A copy of the last route table entry returned by find_route()
+   is saved in {@link Router::$selected_route}.  It can be fetched by
+   a call to {@link Router::get_selected_route()}.  The next call to
+   find_route() overwrites the previous value in
+   $selected_route.</para>
+
+ </refsect1>
+<!--
+Local variables:
+mode: xml
+c-basic-offset: 1
+indent-tabs-mode: nil
+End:
+-->
 </refentry>

trunk/trax/vendor/trax/action_controller.php

@@ -182 +182 @@
  *   }
  *  </pre>
- *
- *  @package PHPonTrax
  */
 class ActionController {
 
-    private
-        $controller,
-        $action,
-        $id,
-        $controllers_path,
-        $helpers_path,
-        $helpers_base_path,
-        $layouts_path,
-        $url_path,
-        $default_layout_file,
-        $helper_file,
-        $application_controller_file,
-        $application_helper_file,
-        $loaded = false,
-        $router_loaded = false,
-        $helpers = array(),
-        $before_filters = array(),
-        $after_filters = array();     
-    protected
-        $before_filter = null,
-        $after_filter = null;
-    public
-        $controller_file,
-        $view_file,
-        $views_path,
-        $controller_class, 
-        $controller_object,
-        $asset_host = null,
-        $views_file_extention = TRAX_VIEWS_EXTENTION;
-
+    /**
+     *  @todo Document this attribute
+     */
+    private $controller;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $action;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $id;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $controllers_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $helpers_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $helpers_base_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $layouts_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $url_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $default_layout_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $helper_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $application_controller_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $application_helper_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $loaded = false;
+
+    /**
+     *  Whether a Router object was loaded
+     *
+     *  @var boolean
+     *  <ul>
+     *    <li>true => $router points to the Router object</li>
+     *    <li>false => no Router object exists</li>
+     *  </ul>
+     */
+    private $router_loaded = false;
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $helpers = array();
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $before_filters = array();
+
+    /**
+     *  @todo Document this attribute
+     */
+    private $after_filters = array();     
+
+    /**
+     *  @todo Document this attribute
+     */
+    protected $before_filter = null;
+
+    /**
+     *  @todo Document this attribute
+     */
+    protected $after_filter = null;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $controller_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $view_file;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $views_path;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $controller_class;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $controller_object;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $asset_host = null;
+
+    /**
+     *  @todo Document this attribute
+     */
+    public $views_file_extention = TRAX_VIEWS_EXTENTION;
+
+    /**
+     *  @todo Document this method
+     */
     function __construct() {
       if(!isset($this->router) || !is_object($this->router)) {
@@ -223 +330 @@
     }
 
+    /**
+     *  @todo Document this method
+     */
     function __set($key, $value) {
         #echo "setting: $key = $value<br>";
@@ -236 +346 @@
     }
 
+    /**
+     *  @todo Document this method
+     */
     function __call($method_name, $parameters) {
         if(method_exists($this, $method_name)) {
@@ -252 +365 @@
     }
 
+    /**
+     *  Load routes from configuration file routes.php
+     *
+     *  Routes are loaded by requiring {@link routes.php} from the
+     *  configuration directory.
+     *  @uses Router
+     *  @uses $router
+     *  @uses $router_loaded
+     */
     function load_router() {
         $this->router_loaded = false;
@@ -263 +385 @@
     }
 
+    /**
+     *  @todo Document this method
+     *  @uses load_router()
+     *  @uses $router
+     *  @uses $router_loaded
+     *  @uses set_paths()
+     *  @uses $url_path
+     */
     function recognize_route() {
 
@@ -341 +471 @@
     }
 
+    /**
+     *  @todo Document this method
+     */
     function process_route() {
 
@@ -346 +479 @@
         if(!$this->loaded) {
             if(!$this->recognize_route()) {
-                $this->raise("Failed to load any defined routes", "Controller ".$this->controller." not found", "404");
+                $this->raise("Failed to load any defined routes",
+                 "Controller ".$this->controller." not found",
+                 "404");
             }
         }
@@ -496 +631 @@
 
         return true;
-    }
-
+    }                                // function process_route()
+
+    /**
+     *  @todo Document this method
+     */
     function set_paths() {
         if(is_array($this->url_path)) {
@@ -681 +819 @@
     }
 
+    /**
+     *  @todo Document this method
+     */
     function determine_layout() {
         # I guess you don't want any layout
@@ -788 +929 @@
 }
 
+// -- set Emacs parameters --
+// Local variables:
+// tab-width: 4
+// c-basic-offset: 4
+// c-hanging-comment-ender-p: nil
+// indent-tabs-mode: nil
+// End:
 ?>

trunk/trax/vendor/trax/router.php

@@ -30 +30 @@
 
 /**
- *
- *  @todo Document this class
- *  @package PHPonTrax
+ *  Convert a URL to an action
+ *  @tutorial PHPonTrax/Router.cls
  */
 class Router {
 
+    /**
+     *  Route table
+     *
+     *  For a description of the structure, see
+     *  {@tutorial PHPonTrax/Router.cls#table the Router tutorial}.
+     *  Routes are added by calling {@link connect()} and looked up
+     *  by calling {@link find_route()}.
+     *  <b>FIXME:</b> Should we have a Route class to describe an
+     *  entry in the route table?
+     *  @var string[][]
+     */
     private $routes = array();
+
+    /**
+     *  Last route found by a call to find_route()
+     *  @var string[]
+     */
     private $selected_route = null;
+
+    /**
+     *  Default route path
+     *
+     *  This route path is added to the route table if the table is
+     *  empty when find_route() is called.
+     *  @var string constant
+     */
     private $default_route_path = ":controller/:action/:id";
+
+    /**
+     *  Count of the number of elements in $routes
+     *  @var integer
+     */
     public $routes_count = 0;
 
     /**
-     *
-     *  @todo Document this method
+     *  Accessor method to return contents of $selected_route
+     *  @return string[] Contents of $selected_route
+     *  @uses $selected_route
      */
     function get_selected_route() {
@@ -50 +79 @@
 
     /**
+     *  Accessor method to add a route to the route table
      *
-     *  @todo Document this method
+     *  The route is added to the end of
+     *  {@link $routes the route table}. If $params is not an array,
+     *  NULL is stored in the route parameter area.
+     *  @param string $path
+     *  @param mixed[] $params
+     *  @uses $routes
+     *  @uses $routes_count
      */
     function connect($path, $params = null) {
@@ -61 +97 @@
 
     /**
+     *  Find first route in route table with path that matches argument
      *
-     *  @todo Document this method
+     *  First, assure that the route table {@link $routes} has at
+     *  least one route by adding
+     *  {@link $default_route_path the default route} if the table is
+     *  empty.  Then search the table to find the first route in the
+     *  table whose path matches the argument $url. If $url is an
+     *  empty string, it matches a path that is an empty string.
+     *  Otherwise, try to match $url to the path part of the table
+     *  entry according to {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}
+     *  rules.  Return the first matching route to the caller, and
+     *  also save a copy in {@link $selected_route}.
+     *  @param string $url
+     *  @uses build_route_regexp()
+     *  @uses $default_route_path
+     *  @uses $routes
+     *  @uses $routes_count
+     *  @uses $selected_route
+     *  @return string[] Selected route. Path is in return['path'],
+     *                   params in return['params'],
      */
     function find_route($url) {
-
         // ensure at least one route (the default route) exists
         if($this->routes_count == 0) {
-            $this->routes['path'] = $this->default_route_path;
-            $this->routes['params'] = null;
+            $this->connect($this->default_route_path);
         }
 
@@ -78 +130 @@
             unset($reg_exp);
             $route_regexp = $this->build_route_regexp($route['path']);
-
             if($url == "" && $route_regexp == "") {
                 $this->selected_route = $route;
@@ -92 +143 @@
 
         return $this->selected_route;
-    }
+    }                                 // function find_route($url)
 
     /**
+     *  Build a regular expression that matches a route
      *
-     *  @todo Document this method
+     *  <b>FIXME:</b> Should this method be private?
+     *  @param string $route_path  A route path.
+     *  @return string Regular expression that matches the route in
+     *                $route_path 
      */
     function build_route_regexp($route_path) {
+        //        echo "entering build_route_regexp(), \$route_path is '$route_path'\n";
 
         $route_regexp = null;
@@ -105 +161 @@
             $route_path = explode("/",$route_path);
         }
-
+        //        echo "route path:\n";
+        //        var_dump($route_path);
         if(count($route_path) > 0) {
             foreach($route_path as $path_element) {
@@ -124 +181 @@
 }
 
+// -- set Emacs parameters --
+// Local variables:
+// tab-width: 4
+// c-basic-offset: 4
+// c-hanging-comment-ender-p: nil
+// indent-tabs-mode: nil
+// End:
 ?>