Changeset 174

Timestamp:

03/13/06 21:10:15 (6 years ago)

Author:

haas

Message:

ActionController? doc done

Location:

trunk/trax

Files:

• app/views/layouts/application.phtml (added)
• test/ActionControllerTest.php (modified) (5 diffs)
• tutorials/PHPonTrax/ActionController.cls (modified) (7 diffs)
• tutorials/PHPonTrax/PHPonTrax.pkg (modified) (4 diffs)
• vendor/trax/action_controller.php (modified) (35 diffs)
• vendor/trax/router.php (modified) (6 diffs)
• vendor/trax/session.php (modified) (2 diffs)

trunk/trax/test/ActionControllerTest.php

@@ -100 +100 @@
         $ac = new ActionController;
         //  this URL doesn't match any route
-        $_SERVER['REDIRECT_URL'] = '~haas/foo/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/foo/bar';
         $this->assertFalse($ac->recognize_route());
         //  this URL matches but the controller doesn't exist
-        $_SERVER['REDIRECT_URL'] = '~haas/nocontroller/foo/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/nocontroller/foo/bar';
         $this->assertFalse($ac->recognize_route());
         //  this URL matches and the controller is where it should be
-        $_SERVER['REDIRECT_URL'] = '~haas/products/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/products/bar';
         $this->assertTrue($ac->recognize_route());
     }
@@ -155 +155 @@
         $ac = new ActionController;
         //  this URL doesn't match any route
-        $_SERVER['REDIRECT_URL'] = '~haas/foo/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/foo/bar';
         try {
             $ac->process_route();
@@ -180 +180 @@
         $ac = new ActionController;
         //  this URL matches default route
-        $_SERVER['REDIRECT_URL'] = '~haas/nocontroller/foo/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/nocontroller/foo/bar';
         try {
             $ac->process_route();
@@ -207 +207 @@
         //  this URL matches default route, but the controller
         //  file doesn't have a Noclass class
-        $_SERVER['REDIRECT_URL'] = '~haas/noclass/foo/bar';
+        $_SERVER['REDIRECT_URL'] = '/~haas/noclass/foo/bar';
         try {
             $ac->process_route();
@@ -234 +234 @@
 //        $ac = new ActionController;
 //        //  should invoke CatalogController
-//        $_SERVER['REDIRECT_URL'] = '~haas/products/bar';
+//        $_SERVER['REDIRECT_URL'] = '/~haas/products/bar';
 //        $ac->process_route();
 //        // Remove the following line when you implement this test.

trunk/trax/tutorials/PHPonTrax/ActionController.cls

@@ -15 +15 @@
  <refsect1 id="{@id intro}">
   <title>Introduction</title>
+  <para>The {@link ActionController} base class does the
+  following:</para>
+  <orderedlist>
+    <listitem>Accepts a URL as input</listitem>
+    <listitem>Translates the URL into a controller and action</listitem>
+    <listitem>Creates the indicated controller object (which is a subclass
+      of ActionController) and calls its action method</listitem>
+    <listitem>Redirects to another URL or renders the output of the
+    action method</listitem> 
+  </orderedlist>
  </refsect1>
- <refsect1 id="{@id filters}">
-  <title>Filters</title>
+ <refsect1 is="{@id url}">
+  <title>URL Processing</title>
+
+  <para>
+   When Apache receives an HTTP request addressed to a Trax
+   application,
+{@link http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html Apache mod_rewrite}
+   is invoked and rewrites the request to invoke Trax file
+   <literal>dispatch.php</literal>.  At this time the URL which was
+   input to the rewrite rules is in
+{@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.server $_SERVER}['REDIRECT_URL'].  
+   <literal>dispatch.php</literal> creates a new {@link Dispatcher}
+   object and calls its 
+   {@link Dispatcher::dispatch() dispatch()} method. dispatch()
+   restores the state of the session identified by a cookie in the
+   request, or creates a session if none exists.  Then it creates a
+   new ActionController object and calls its
+   {@link ActionController::process_route() <literal>process_route()</literal>} 
+   method. 
+  </para>
+
+  <para>
+   The word "route" is used in Trax to describe a rule which
+   translates some URL into a particular controller object and method.
+   When <literal>process_route()</literal> receives control, it calls
+   {@link ActionController::recognize_route() recognize_route()} to
+   parse the URL into controller, action and id
+   components. recognize_route() calls
+   {@link ActionController::load_router() load_router()} to load the
+   "routing table", which is a list of one or more
+   <literal>$router->connect()</literal> calls, from
+   {@link routes.php <literal>config/routes.php</literal>}.  
+   This list of calls define the rules for translating a URL into a
+   controller and action.
+  </para>
+
+  <para>
+   The translation rules work as follows:  Starting with the first
+   rule in <literal>routes.php</literal>, each rule is tested against
+   the URL to see 
+   whether the rule matches.  If a rule does not match, then the next
+   rule in the table is tested in turn, until a rule matches or the
+   table is exhausted.  If no matching rule is found,
+   recognize_route() tests the last route in the table to see whether
+   it is the default route <literal>:controller/:action/:id</literal>
+   .  If the last route is the default route, then
+   <literal>recognize_route()</literal>
+   returns it as a match, even if it does not in fact match.  But if
+   there is no matching route and the last route in the table is not
+   the default route, then recognize_route() returns 'failure' which is
+   equivalent to HTTP code '404&nbsp;Not&nbsp;found'.
+  </para>
+
+  <para>
+   Each entry in the route table contains two parts:
+   <orderedlist>
+    <listitem>
+     A <important>path</important>, which is a character string to
+     test against the URL.
+    </listitem>
+    <listitem>
+     <important>Parameters</important>, which are not tested against
+     the URL and aren't involved unless the
+     <important>path</important> part of the entry matches the URL.
+     <important>Parameters</important> are optional (and frequently
+     omitted).
+    </listitem>
+   </orderedlist>
+   A <important>path</important> is a series of substrings separated
+   by '/' (forward slash) characters.  Each of these substrings can
+   contain any character except '/'.  The <important>path</important>
+   does not begin or end with '/'.  A substring may not be the null
+   (no characters) string, but it is legal for the entire
+   path to be the null string. Each substring is one of the following:
+   <itemizedlist>
+    <listitem><literal>:controller</literal></listitem>
+    <listitem><literal>:action</literal></listitem>
+    <listitem><literal>:id</literal></listitem>
+    <listitem>A
+     {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}
+     that does not begin with ':' (colon)</listitem>
+   </itemizedlist>
+   The following are legal <important>path</important> values:
+   <itemizedlist>
+    <listitem><literal>:controller/:action/:id</literal>
+     This is the default <important>path</important>. It matches URLs
+     like <literal>word1/word2/word3</literal></listitem>
+    <listitem><literal>catalog/product/:action/:id</literal>
+     Remember that <literal>catalog</literal> is a Perl regular
+     expression that matches <literal>catalog</literal>, and
+     <literal>product</literal> is a Perl regular expression that
+     matches <literal>product</literal>, so this
+     <important>path</important> matches URLs like 
+     <literal>catalog/product/word1/word2</literal></listitem>
+    <listitem><literal>''</literal> matches '' (the empty string as a 
+     <important>path</important> value matches the empty string as a
+     URL).</listitem>
+    <listitem><literal>member/name=.*</literal> matches URLs like
+     <literal>member/name=</literal> or
+     <literal>member/name=Tom.Jones</literal> or
+     <literal>member/name=Smith,J/since=1987/type=full</literal> etc.
+    </listitem>
+   </itemizedlist>
+   <literal>:controller</literal>, <literal>:action</literal> and
+   <literal>:id</literal> may each appear at most once in a 
+   <important>path</important>.
+  </para>
+
+  <para>
+   After the URL has been matched to a <important>path</important>,
+   the next step is to extract the name of the controller and action
+   to be invoked on this URL.  These must be valid names in the PHP
+   language consisting only of lower-case alphameric characters and
+   '_' (underscore), because the controller name will translate
+   directly into a file name and a class name, and the action name
+   will be used as the name of a method in that class.  The controller
+   and action names come from the route that matches the URL.
+  </para>
+
+  <para>
+   There are two places that a route can specify a controller or
+   action name: as part of the <important>path</important>, or in the 
+   <important>parameters</important>.  The
+   <important>parameters</important> are the optional second part of a
+   route.  The value of <important>parameters</important> is an array
+   with key values that may be <literal>:controller</literal> or
+   <literal>:action</literal>.  The following are legal
+   <important>parameters</important> values:
+   <itemizedlist>
+    <listitem><literal>array(':controller' =>
+     'new_product')</literal></listitem> 
+    <listitem><literal>array(':action' => 'enter')</literal></listitem>
+    <listitem><literal>array(':controller' => 'membership', ':action
+     => 'new')</literal></listitem> 
+   </itemizedlist>    
+  </para>
+
+  <para>
+   When a URL matches a route, the controller name is extracted as
+   follows:  First, if the <important>parameters</important> array
+   exists and has an element whose key is
+   <literal>:controller</literal>, then the value of that element is
+   used as the controller name.  If no <literal>:controller</literal>
+   is specified by the <important>parameters</important>, then the
+   <important>path</important> is tested for a substring whose value
+   is <literal>:controller</literal>.  If found, then the part of the
+   URL which matched that substring is used as the controller value.
+   A controller value must be specified by either the
+   <important>parameters</important> or the
+   <important>path</important>.  The action name is extracted by the
+   same process, substituting <literal>:action</literal> for 
+   <literal>:controller</literal>.  If the
+   <important>path</important> has a substring <literal>:id</literal>,
+   then the part of the URL which matched that substring is forced to
+   lower case and the result assigned to
+   <literal>$_REQUEST['id']</literal>.
+  </para>
+
+  <para>
+   If <literal>routes.php</literal> contains the following:
+   <example>
+router->connect('',array(':controller' => 'home'));
+router->connect('product\?.*',
+                array(':controller' => 'catalog', ':action' => 'find'));
+router->connect(':controller/:action/:id');
+   </example>
+   Then URLs will match routes as follows:
+   <itemizedlist>    
+    <listitem>URL <literal>''</literal> (no characters) will select
+     controller <literal>home</literal>, action not specified.
+    </listitem>
+    <listitem>URL <literal>product?item=4317</literal> will select
+     controller <literal>catalog</literal>, action
+     <literal>find</literal>
+    </listitem>
+    <listitem>URL <literal>cart/add/4317</literal> will select
+     controller <literal>cart</literal>, action <literal>add</literal>
+    </listitem>
+   </itemizedlist>    
+  </para>
+
+ </refsect1>
+ <refsect1 is="{@id action}">
+  <title>Action Call</title>
+  <para>When the names of the controller and action have been
+   successfully determined from the URL, the associated filesystem
+   paths are constructed and relevant files are loaded.
+   First file <literal>app/controllers/application.php</literal> is
+   loaded if it exists. This file contains the definition of the
+   {@link ApplicationController} class, which extends
+   <literal>ActionController</literal>.
+   <literal>ApplicationController</literal> contains properties and
+   methods used by all the controller classes, which should extend
+   <literal>ApplicationController</literal> .
+   Then the controller name is used to find the file and class
+   containing the selected controller.  By Trax naming conventions, 
+   if the controller name is
+   <arg choice="tute-comment">controller&nbsp;name</arg>
+   then the controller file name is
+   <arg choice="tute-comment">controller_name</arg><literal>_controller.php</literal>
+   and the controller class name is
+   <arg choice="tute-comment">ControllerName</arg> .  So for a
+   "catalog&nbsp;item" controller, the controller file name is
+   <literal>catalog_item_controller</literal> and the controller class
+   name is <literal>CatalogItem</literal>.
+   The controller file is loaded and a new object of the controller
+   class is created.
+  </para>
+
+  <para>
+   Next any needed helper files are loaded.  Helper files contain PHP
+   code which helps prepare the output of an action method for
+   viewing. If file
+   <literal>application_helper.php</literal> exists, it is loaded.
+   <literal>application_helper.php</literal> contains
+   helpers that apply to every controller in the application.
+   Then the controller-specific helper file
+   <arg choice="tute-comment">controller_name</arg><literal>_helper.php</literal>
+   is loaded if it exists.  Finally any extra helper files, as
+   specified by calls to {@link ActionController::add_helper()}, are
+   loaded.
+  </para>
+
+  <para>
+   When controller and helper files have been loaded, the before
+   filters are executed (<important>FIXME:</important> We should check
+   return but don't).  Next the controller object is tested for the
+   presence of a method with the name of the action as determined from
+   the URL. If such a method exists, it is called; if 
+   no such method exists, then the controller object is tested
+   for the presence of a method named <literal>index()</literal>.
+   If such a method exists it is called, otherwise the request fails
+   with 404&nbsp;Unknown&nbsp;action. If an action method was found
+   and called, the after filters are executed.
+  </para>
+
+  <refsect2 id="{@id helpers}">
+   <title>Helper Loading</title>
+   <para>Helpers are classes that provide view logic.  They exist to
+    hold view logic that would otherwise need to be added to a
+    template or controller.  Helper services that are applicable to
+    the entire application go into
+    <literal>application_helper.php</literal>, while
+    controller-specific helper functions go into a helper file named
+    after the controller, as 
+    <arg choice="tute-comment">controller_name</arg><literal>_helper.php</literal> 
+    . Helper classes are written as subclasses of class {@link Helpers},
+    which has a number of methods widely used by helper
+    subclasses.  You can add a helper to an
+    <literal>ActionController</literal> object by calling its
+    {@link ActionController::add_helper() add_helper()} 
+    method, passing the name of the helper as an argument.
+   </para>
+
+   <para>
+    A number of predefined helper classes are distributed with Trax:
+    <itemizedlist>
+     <listitem>{@link ActiveRecordHelper}</listitem>
+     <listitem>{@link AssetTagHelper}</listitem>
+     <listitem>{@link DateHelper}</listitem>
+     <listitem>{@link FormHelper}</listitem>
+     <listitem>{@link FormTagHelper}</listitem>
+     <listitem>{@link JavaScriptHelper}</listitem>
+     <listitem>{@link UrlHelper}</listitem>
+    </itemizedlist>
+    These classes are <important>not</important> automatically loaded,
+    you have to load them explicitly.
+   </para>
+   <para></para>
+  </refsect2>
+
+  <refsect2 id="{@id filters}">
+   <title>Filters</title>
 
    <para>Filters enable controllers to run shared pre and post
@@ -30 +311 @@
     for a pre-processing <samp>before_filter</samp> to halt the processing
     before the intended action is processed by returning false or
-    performing a redirect or render.  This is especially useful for
+    performing a redirect or render. (FIXME: we don't implement this)
+    This is especially useful for
     filters like authentication where you're not interested in
     allowing the action to be  performed if the proper credentials are
     not in order.</para>
 
-   <refsect2 id="{@id filter_inherit}">
+   <refsect3 id="{@id filter_inherit}">
     <title>Filter inheritance</title>
 
@@ -66 +348 @@
      audit method is called, then the verify_credentials method. If the
      audit method returns false, then verify_credentials and the
-     intended action are never called.</para>
-    </refsect2>
-
-    <refsect2 id="{@id filter_types}">
+     intended action are never called.  <important>FIXME:
+     This is currently broken.</important></para>
+    </refsect3>
+
+    <refsect3 id="{@id filter_types}">
      <title>Filter types</title>
 
@@ -120 +403 @@
       have to be a block; any object that responds to call and returns 1
       or -1 on arity will do (such as a Proc or an Method object).</para>
-    </refsect2>
-
-    <refsect2 id="{@id filter_skip}">
+    </refsect3>
+
+    <refsect3 id="{@id filter_skip}">
      <title>Filter chain skipping</title>
 
@@ -142 +425 @@
 }
      </example>
-    </refsect2>
-
-    <refsect2 id="{@id filter_conditions}">
+    </refsect3>
+
+    <refsect3 id="{@id filter_conditions}">
      <title>Filter conditions</title>
 
@@ -169 +452 @@
       condition must come first and be placed in parentheses.</para>
  
-   <example>
+    <example>
 class UserPreferences extends ActionController
 {
@@ -175 +458 @@
     ...
 }
-  </example>
+    </example>
+   </refsect3>
   </refsect2>
+ </refsect1>
+ <refsect1 id="{@id render}">
+  <title>Redirect Browser or Render Output</title>
+
+  <para>After the controller object's action method has returned to
+   <literal>ActionController::process_route()</literal> and the after
+   filters have been executed, the controller object is examined for
+   a property named <literal>redirect_to</literal>.  If this
+   property exists and has a value, it means that the action method
+   has decided to redirect the user's browser to a different URL.  The
+   value of the <literal>redirect_to</literal> property is passed to
+   {@link ActionController::redirect_to() <literal>redirect_to()</literal>}
+   which outputs a header redirecting the browser, then calls
+   {@link http://www.php.net/manual/en/function.exit.php exit} .</para>
+
+  <para>
+   If the action didn't redirect the browser, it should have provided
+   output to send to the browser.  This is in the form of explicit
+   output produced by calls to
+   {@link http://www.php.net/manual/en/function.echo.php echo},
+   {@link http://www.php.net/manual/en/function.print.php print} or
+   {@link http://www.php.net/manual/en/function.printf.php printf} ,
+   plus any properties of the controller object that are referenced in
+   the layout. <literal>ActionController::process_route()</literal>
+   collects all output produced by the controller's action method
+   in the output buffer, for presentation within a layout.
+  </para>
+
+  <para>
+   If the controller object has a property
+   <literal>render_text</literal> which contains a string, then this
+   string is sent directly to the browser and all output and view
+   files are ignored.
+  </para>
+
+  <para>
+   If <literal>render_text</literal> is undefined or empty, then the
+   saved output of the controller's action method is to be rendered.
+   A <important>view file</important> determined by the action is
+   found and included.  The view file for an action is
+   <literal>app/views/</literal><arg choice="tute-comment">controller_name/action_name</arg><literal>.phtml</literal> .
+   This file contains HTML, which goes to the output buffer after the
+   action method's output.  The output buffer is now assigned to
+   $content_for_layout.  Finally the layout file is loaded.  The
+   view file and layout file both contain HTML with
+   {@link http://www.php.net/manual/en/language.basic-syntax.php embedded PHP}
+   expressions to present action method output to the user.
+  </para>
  </refsect1>
 <!--

trunk/trax/tutorials/PHPonTrax/PHPonTrax.pkg

@@ -269 +269 @@
      To:
      <example>
-RewriteRule ^(.*)$ ~haas/dispatch.php?$1 [QSA,L]
+RewriteRule ^(.*)$ /~haas/dispatch.php?$1 [QSA,L]
      </example>
      </listitem>
@@ -303 +303 @@
      <listitem>
      With your favorite editor, open file
-     ~/trax/config/environment.php and change the line that defines
-     TRAX_URL_PREFIX to:
+     <literal>~/trax/config/environment.php</literal> and change the
+     line that defines <literal>TRAX_URL_PREFIX</literal> to:
      <example>
 define("TRAX_URL_PREFIX", "~haas");
      </example>
-     </listitem>
-
-     <listitem>
-     Change file permissions on the log files in ~/trax/log so that
-     Apache can write to them:
+     Also edit the line that defines <literal>TRAX_PUBLIC</literal> to
+     change <literal>public</literal> to <literal>public_html</literal>.
+     </listitem>
+
+     <listitem>
+     Change file permissions on the log files in
+     <literal>~/trax/log</literal> so that Apache can write to them:
      <example>
 $ <important>su -</important>
@@ -393 +395 @@
   <refsect2 id="{@id ref_defines}">
    <title>Defines</title>
+   All the definitions below are set in file
+  {@link environment.php config/environment.php}
    <itemizedlist>
+
+    <listitem><command>DEBUG</command>
+     <cmdsynopsis>boolean set to true if TRAX_MODE is 'development',
+     false otherwise.  Determines whether PHP error messages should be
+     sent to the browser; true means show error messages on the
+     browser as well as the error log, false means send error messages
+     to only the error log.  Implemented by calling
+     {@link http://www.php.net/ini_set ini_set()}
+     at the time DEBUG is defined.
+     </cmdsynopsis>
+    </listitem>
+
+    <listitem><command>PHP_LIB_ROOT</command>
+     <cmdsynopsis>Directory containing PHP libraries.  This directory
+     will be added to the PHP
+     {@link http://www.php.net/manual/en/ini.core.php#ini.include-path include path}.
+     </cmdsynopsis>
+    </listitem>
+
+    <listitem><command>TRAX_LIB_ROOT</command>
+     <cmdsynopsis>Directory containing Trax libraries.  Set to a
+     subdirectory of TRAX_ROOT or PHP_LIB_ROOT and added to the PHP
+     {@link http://www.php.net/manual/en/ini.core.php#ini.include-path include path}.
+     </cmdsynopsis>
+    </listitem>
 
     <listitem><command>TRAX_MODE</command>
@@ -401 +430 @@
     </listitem>
 
+    <listitem><command>TRAX_PATH_SEPERATOR</command>
+     <cmdsynopsis>Character to use as the separator when defining the
+     PHP include path. ';' for Windows, otherwise ':'.
+     </cmdsynopsis>
+    </listitem>
+
+    <listitem><command>TRAX_PUBLIC</command>
+     <cmdsynopsis>Subdirectory of the user's home directory referenced
+     by the Apache configuration variable <literal>UserDir</literal>.
+     </cmdsynopsis>
+    </listitem>
+
+    <listitem><command>TRAX_ROOT</command>
+     <cmdsynopsis>Filesystem path to the top of the Trax file tree.
+     </cmdsynopsis>
+    </listitem>
+
+    <listitem><command>TRAX_URL_PREFIX</command>
+     <cmdsynopsis>That part of a URL which refers to a Trax
+     application that comes after the domain name and before the
+     controller.  Usually empty.  In the case of a Trax application in
+     the home directory of user <literal>username</literal>,
+     <command>TRAX_URL_PREFIX</command> would be set to 
+     '<literal>~username</literal>'.
+     </cmdsynopsis>
+    </listitem>
+
     <listitem><command>TRAX_VIEWS_EXTENTION</command>
-     <cmdsynopsis>file extension for views</cmdsynopsis>
-    </listitem>
-
-    <listitem><command></command>
-     <cmdsynopsis>
-     </cmdsynopsis>
-    </listitem>
-
-    <listitem><command></command>
-     <cmdsynopsis>
-     </cmdsynopsis>
-    </listitem>
-
-    <listitem><command></command>
-     <cmdsynopsis>
-     </cmdsynopsis>
-    </listitem>
-
-    <listitem><command></command>
-     <cmdsynopsis>
-     </cmdsynopsis>
-    </listitem>
-
-    <listitem><command></command>
-     <cmdsynopsis>
-     </cmdsynopsis>
+     <cmdsynopsis>File extension for views, default
+     'phtml'.</cmdsynopsis>
     </listitem>
 

trunk/trax/vendor/trax/action_controller.php

@@ -32 +32 @@
  *  Action controller
  *
- *  <p><b>Filters</b></p>
+ *  <p>The ActionController base class operates as follows:</p>
+ *  <ol>
+ *    <li>Accept a URL as input</li>
+ *    <li>Translate the URL into a controller and action</li>
+ *    <li>Create the indicated controller object (which is a subclass
+ *      of ActionController) and call its action method</li>
+ *    <li>Render the output of the action method</li>
+ *    <li>Redirect to the next URL</li>
+ *  </ol>
  *
- *  <p>Filters enable controllers to run shared pre and post
- *  processing code for its actions. These filters can be used to do
- *  authentication, caching, or auditing before the intended action is
- *  performed. Or to do localization or output compression after the
- *  action has been performed.</p>
- *
- *  <p>Filters have access to the request, response, and all the
- *  instance variables set by other filters in the chain or by the
- *  action (in the case of after filters). Additionally, it's possible
- *  for a pre-processing <samp>before_filter</samp> to halt the processing
- *  before the intended action is processed by returning false or
- *  performing a redirect or render.  This is especially useful for
- *  filters like authentication where you're not interested in
- *  allowing the action to be  performed if the proper credentials are
- *  not in order.</p>
- *
- *  <p><b>Filter inheritance</b></p>
- *
- *  <p>Controller inheritance hierarchies share filters downwards, but
- *  subclasses can also add new filters without affecting the
- *  superclass. For example:</p>
- *
- *  <pre>
- *   class BankController extends ActionController
- *   {
- *     $this->before_filter = audit();
- *
- *     private function audit() {
- *       <i>record the action and parameters in an audit log</i>
- *     }
- *   }
- *
- *   class VaultController extends BankController
- *   {
- *     $this->before_filter = verify_credentials();
- *
- *     private function verify_credentials() {
- *       <i>make sure the user is allowed into the vault</i>
- *     }
- *   }
- *  </pre>
- *
- *  <p>Now any actions performed on the BankController will have the
- *  audit method called before. On the VaultController, first the
- *  audit method is called, then the verify_credentials method. If the
- *  audit method returns false, then verify_credentials and the
- *  intended action are never called.</p>
- *
- *  <p><b>Filter types</b></p>
- *
- *  <p>A filter can take one of three forms: method reference
- *  (symbol), external class, or inline method (proc). The first is the
- *  most common and works by referencing a protected or private method
- *  somewhere in the inheritance hierarchy of the controller by use of
- *  a symbol. In the bank example above, both BankController and
- *  VaultController use this form.</p>
- *
- *  <p>Using an external class makes for more easily reused generic
- *  filters, such as output compression. External filter classes are
- *  implemented by having a static +filter+ method on any class and
- *  then passing this class to the filter method. Example:</p>
- *
- *  <pre>
- *   class OutputCompressionFilter
- *   {
- *     static functionfilter(controller) {
- *       controller.response.body = compress(controller.response.body)
- *     }
- *   }
- *
- *   class NewspaperController extends ActionController
- *   {
- *     $this->after_filter = OutputCompressionFilter;
- *   }
- *  </pre>
- *
- *  <p>The filter method is passed the controller instance and is
- *  hence granted access to all aspects of the controller and can
- *  manipulate them as it sees fit.</p>
- *
- *  <p>The inline method (using a proc) can be used to quickly do
- *  something small that doesn't require a lot of explanation.  Or
- *  just as a quick test. It works like this:</p>
- *
- *  <pre>
- *   class WeblogController extends ActionController
- *   {
- *     before_filter { |controller| false if controller.params["stop_action"] }
- *   }
- *  </pre>
- *
- *  <p>As you can see, the block expects to be passed the controller
- *  after it has assigned the request to the internal variables.  This
- *  means that the block has access to both the request and response
- *  objects complete with convenience methods for params, session,
- *  template, and assigns. Note: The inline method doesn't strictly
- *  have to be a block; any object that responds to call and returns 1
- *  or -1 on arity will do (such as a Proc or an Method object).</p>
- *
- *  <p><b>Filter chain skipping</b></p>
- *
- *  <p>Some times its convenient to specify a filter chain in a superclass 
- *  that'll hold true for the majority of the subclasses, but not necessarily
- *  all of them. The subclasses that behave in exception can then specify
- *  which filters they would like to be relieved of. Examples</p>
- *
- *  <pre>
- *   class ApplicationController extends ActionController
- *   {
- *     $this->before_filter = authenticate();
- *   }
- *
- *   class WeblogController extends ApplicationController
- *   {
- *      // will run the authenticate() filter
- *   }
- *  </pre>
- *
- *  <p><b>Filter conditions</b></p>
- *
- *  <p>Filters can be limited to run for only specific actions. This
- *  can be expressed either by listing the actions to exclude or
- *  the actions to include when executing the filter. Available
- *  conditions are +:only+ or +:except+, both of which accept an
- *  arbitrary number of method references. For example:</p>
- *
- *  <pre>
- *   class Journal extends ActionController
- *   {
- *     // only require authentication if the current action is edit or delete
- *     before_filter :authorize, :only => [ :edit, :delete ]
- *    
- *     private function authorize() {
- *      // redirect to login unless authenticated
- *     }
- *   }
- *  </pre>
- * 
- *  <p>When setting conditions on inline method (proc) filters the
- *  condition must come first and be placed in parentheses.</p>
- *
- *  <pre>
- *   class UserPreferences extends ActionController
- *   {
- *     before_filter(:except => :new) { ? some proc ... }
- *  * ...
- *   }
- *  </pre>
+ *  For details see the
+ *  {@tutorial PHPonTrax/ActionController.cls class tutorial}
  */
 class ActionController {
@@ -202 +64 @@
 
     /**
-     *  @todo Document this attribute
+     *  Value of :id parsed from URL then forced to lower case
+     *
+     *  Set by {@link recognize_route()}
+     *  @var string
      */
     private $id;
@@ -223 +88 @@
 
     /**
+     *  Filesystem path to ../app/helpers/<i>extras</i> directory
+     *
+     *  Set by {@link recognize_route()}, {@link set_paths()}
+     *  @var string
+     */
+    private $helpers_path;
+
+    /**
      *  Filesystem path to ../app/helpers/ directory
      *
@@ -228 +101 @@
      *  @var string
      */
-    private $helpers_path;
-
-    /**
-     *  @todo Document this attribute
-     */
     private $helpers_base_path;
 
     /**
-     *  Filesystem path to ../app/layouts/ directory
-     *
-     *  Set by {@link recognize_route()}
-     *  @todo <b>FIXME:</> declare $layouts_base_path
+     *  Filesystem path to ../app/views/layouts/<i>extras</i> directory
+     *
+     *  Set by {@link recognize_route()}, {@link set_paths()}
      *  @var string
      */
     private $layouts_path;
+
+    /**
+     *  Filesystem path to ../app/views/layouts/ directory
+     *
+     *  Set by {@link recognize_route()}
+     *  @var string
+     */
+    private $layouts_base_path;
 
     /**
@@ -263 +138 @@
 
     /**
-     *  @todo Document this attribute
+     *  Filesystem path to the controllername_helper.php file
+     *
+     *  Set by {@link recognize_route()}
+     *  @var string
      */
     private $helper_file;
@@ -306 +184 @@
 
     /**
+     *  List of additional helper files for this controller object
+     *
+     *  Set by {@link add_helper()}
+     *  @var string[]
+     */
+    private $helpers = array();
+
+    /**
+     *  List of filters to execute before calling action method
+     *
+     *  Set by {@link add_before_filters()
+     *  @var string[]
+     */
+    private $before_filters = array();
+
+    /**
+     *  List of filters to execute after calling action method
+     *
+     *  Set by {@link add_after_filters()
+     *  @var string[]
+     */
+    private $after_filters = array();     
+
+    /**
      *  @todo Document this attribute
      */
-    private $helpers = array();
+    protected $before_filter = null;
 
     /**
      *  @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;
 
@@ -340 +227 @@
 
     /**
-     *  @todo Document this attribute
+     *  Filesystem path to the view file selected for this action
+     *
+     *  Set by {@link process_route()
+     *  @var string
      */
     public $view_file;
@@ -371 +261 @@
     /**
      *  @todo Document this attribute
+     *  @todo <b>FIXME:</b> Not referenced in this class - is it used
+     *        by subclasses?  If so, for what?
      */
     public $asset_host = null;
 
     /**
-     *  @todo Document this attribute
+     *  File extension appended to view files
+     *
+     *  Set from a define in {@link environment.php}.  Usually phtml
+     *  @var string
      */
     public $views_file_extention = TRAX_VIEWS_EXTENTION;
@@ -462 +357 @@
      *  Convert URL to controller, action and id
      *
-     *  Parse the URL in $_SERVER['REDIRECT_URL'] into elements.
+     *  Parse the URL in
+     *  {@link
+     *  http://www.php.net/manual/en/reserved.variables.php#reserved.variables.server $_SERVER}['REDIRECT_URL']
+     *  into elements.
      *  Compute filesystem paths to the various components used by the
      *  URL and store the paths in object private variables.
@@ -499 +397 @@
         # current url
         $browser_url = $_SERVER['REDIRECT_URL'];
+        //error_log('browser url='.$browser_url);
         # strip off url prefix, if any
         if(!is_null(TRAX_URL_PREFIX)) {
-            $browser_url = str_replace(TRAX_URL_PREFIX,"",$browser_url);
-        }
+            // FIXME: Do we know for sure that the
+            // initial '/' will be there?
+            $browser_url = str_replace('/'.TRAX_URL_PREFIX,"",$browser_url);
+        }
+        //error_log('browser url='.$browser_url);
 
         # strip leading slash
+        // FIXME: Do we know for sure that the
+        // initial '/' will be there?
         $browser_url = substr($browser_url,1);
+        //error_log('browser url='.$browser_url);
 
         # strip trailing slash (if any)
@@ -511 +416 @@
             $browser_url = substr($browser_url, 0, -1);
         }
+        //error_log('browser url='.$browser_url);
 
         if($browser_url) {
@@ -528 +434 @@
 
             $route = $this->router->find_route($browser_url);
+
+            //  find_route() returns an array if it finds a path that
+            //  matches the URL, null if no match found
             if(is_array($route)) {
                 $this->set_paths();
@@ -538 +447 @@
                     $this->controller = strtolower($this->url_path[@array_search(":controller", $route_path)]);
                 }
-
+                //error_log('controller='.$this->controller);
                 if(@array_key_exists(":action",$route_params)) {
                     $this->action = $route_params[':action'];
@@ -546 +455 @@
                     $this->action = strtolower($this->url_path[@array_search(":action", $route_path)]);
                 }
-
+                //error_log('action='.$this->action);
+                //  FIXME: RoR uses :name as a keyword parameter, id
+                //  is not treated as a special case.
+                //  Do we want to do the same?
                 if(@in_array(":id",$route_path)
                    && array_key_exists(@array_search(":id", $route_path),
@@ -555 +467 @@
                     }
                 }
-
+                //error_log('id='.$this->id);
                 $this->views_path .= "/" . $this->controller;
                 $this->controller_file = $this->controllers_path . "/" .  $this->controller . "_controller.php";
@@ -573 +485 @@
 
     /**
-     *  @todo Document this method
+     *  Parse URL, extract controller and action and execute them
+     *
      *  @uses $action
      *  @uses $application_controller_file
@@ -591 +504 @@
      *  @uses raise()
      *  @uses ScaffoldController
-     *  @uses Session::unset()
+     *  @uses Session::unset_var()
      *  @uses $view_file
      *  @uses $views_file_extention
@@ -599 +512 @@
     function process_route() {
 
+        $render_layout = true;
         # First try to load the routes and setup the paths to everything
         if(!$this->loaded) {
@@ -616 +530 @@
         }
 
-        error_log('process_route() controller="'.$this->controller
-                  .'"  action="'.$this->action.'"');
+        //error_log('process_route() controller="'.$this->controller
+        //          .'"  action="'.$this->action.'"');
         # Include the controller file and execute action
         // FIXME: redundant, recognize_route() already test for file exists
-        if(file_exists($this->controller_file)) {
+        if (file_exists($this->controller_file)) {
             include_once($this->controller_file);
             if(class_exists($this->controller_class,false)) {
@@ -633 +547 @@
                     $GLOBALS['current_action_name'] = $this->action;
                     $GLOBALS['current_controller_object'] =& $this->controller_object;
-                    error_log('$GLOBALS[\'current_action_name\']='
-                              .$GLOBALS['current_action_name']);
-                    error_log('$GLOBALS[\'current_controller_name\']='
-                              .$GLOBALS['current_controller_name']);
-                    error_log('$GLOBALS[\'current_controller_path\']='
-                              .$GLOBALS['current_controller_path']);
+                    // error_log('$GLOBALS[\'current_action_name\']='
+                    //           .$GLOBALS['current_action_name']);
+                    // error_log('$GLOBALS[\'current_controller_name\']='
+                    //           .$GLOBALS['current_controller_name']);
+                    // error_log('$GLOBALS[\'current_controller_path\']='
+                    //           .$GLOBALS['current_controller_path']);
                 }
 
                 # Which layout should we use?
                 $layout_file = $this->determine_layout();
-                error_log('layout_file="'.$layout_file.'"');
-                # Check if there is any defined scaffolding to load
+                // error_log('layout_file="'.$layout_file.'"');
+                // # Check if there is any defined scaffolding to load
                 if(isset($this->controller_object->scaffold)) {
                     $scaffold = $this->controller_object->scaffold;
@@ -694 +608 @@
                 # Call the controller method based on the URL
                 $this->execute_before_filters();
+                // FIXME: shouldn't we check return here?
                 if(method_exists($this->controller_object, $this->action)) {
-                    error_log('controller has method "'.$this->action.'"');
+                    //error_log('controller has method "'.$this->action.'"');
                     $action = $this->action;
                     $this->controller_object->$action();
                 } elseif(file_exists($this->views_path . "/" . $this->action . "." . $this->views_file_extention)) {
-                    error_log('views file "'.$this->action.'"');
+                    // error_log('views file "'.$this->action.'"');
                     $action = $this->action;
                 } elseif(method_exists($this->controller_object, "index")) {
-                    error_log('calling index()');
+                    //error_log('calling index()');
                     $this->controller_object->index();
                 } else {
-                    error_log('no action');
+                    //error_log('no action');
                     $this->raise("No action responded to ".$this->action, "Unknown action", "404");
                 }
@@ -714 +629 @@
                     && $this->controller_object->redirect_to != '') {
                     $this->redirect_to($this->controller_object->redirect_to);
+                    //  redirect_to() exits instead of returning
                 } else {
                     # Pull all the class vars out and turn them from $this->var to $var
@@ -725 +641 @@
                     # If this isn't a scaffolding then get the view file to include
                     if(!isset($scaffold)) { 
+                        // error_log('not scaffolding, looking for view file');
                         # Normal processing of the view
                         if(isset($this->controller_object->render_action)
@@ -735 +652 @@
                             $this->view_file = $this->views_path . "/" . "index" . "." . $this->views_file_extention;
                         }
+                        // error_log('view file='.$this->view_file);
                     }
 
@@ -748 +666 @@
                     ob_end_clean();
 
+                    //error_log('layout file='.$layout_file
+                    //          .'  render_layout='
+                    //          .var_export($render_layout,true));
                     if(file_exists($layout_file) && $render_layout !== false) {
                         # render the layout
@@ -765 +686 @@
         }
 
+        // error_log('keep flash='.var_export($this->keep_flash,true));
         if(!$this->keep_flash) {
             # Nuke the flash
@@ -774 +696 @@
 
     /**
-     *  @todo Document this method
+     *  Extend the search path for components
+     *
+     *  On entry, $url_path is set according to the browser's URL and 
+     *  $controllers_path has been set according to the configuration
+     *  in {@link environment.php config/environment.php} .  Examine
+     *  the $controllers_path directory for files or directories that
+     *  match any component of the URL.  If one is found, add that
+     *  component to all paths.  Replace the contents of $url_path
+     *  with the list of URL components that did NOT match any files
+     *  or directories.
      *  @uses $added_path
      *  @uses $controllers_path
      *  @uses $helpers_path
-     *  @uses $layous_path
+     *  @uses $layouts_path
      *  @uses $views_path
      *  @uses $url_path
+     *  @todo <b>FIXME:</b> Creating a file or directory in
+     *        app/controllers with the same name as a controller, action or
+     *        other URL element will hijack the browser!
      */
     function set_paths() {
@@ -808 +742 @@
     /**
      *  Execute the before filters
+     *  @uses $before_filters
      */
     function execute_before_filters() {
@@ -825 +760 @@
      *  one filter function, or array of strings with the names of
      *  several filter functions.
+     *  @uses $before_filters
      */
     function add_before_filter($filter_function_name) {
@@ -840 +776 @@
     }
 
+    /**
+     *  Execute the after filters
+     *  @uses $after_filters
+     */
     function execute_after_filters() {
         if(count($this->controller_object->after_filters) > 0) {
@@ -857 +797 @@
      *  one filter function, or array of strings with the names of
      *  several filter functions.
+     *  @uses $after_filters
      */
     function add_after_filter($filter_function_name) {
@@ -872 +813 @@
     }
 
+    /**
+     *  Add a helper to the list of helpers used by a controller
+     *  object
+     *
+     *  @param $helper_name string Name of a helper to add to the list
+     *  @uses  $helpers
+     *  @uses  $controller_object
+     */
     function add_helper($helper_name) {
         if(!in_array($helper_name, $this->controller_object->helpers)) {
@@ -969 +918 @@
 
     /**
-     *  @todo Document this method
+     *  Select a layout file based on the controller object
+     *
      *  @uses $controller_object
      *  @uses $layouts_base_path
@@ -979 +929 @@
         # I guess you don't want any layout
         if($this->controller_object->layout == "null") {
+            //error_log('controller->layout absent');
             return null;
         }
@@ -1015 +966 @@
 
     /**
-     * Redirects the browser to the target specified in options. This parameter can take one of three forms:
-     * 
-     *     * Array: The URL will be generated by calling url_for() with the options.
-     *     * String starting with protocol:// (like http://): Is passed straight through as the target for redirection.
-     *     * String not containing a protocol: The current protocol and host is prepended to the string.
-     *     * back: Back to the page that issued the request. Useful for forms that are triggered from multiple places. Short-hand for redirect_to(request.env["HTTP_REFERER"])
-     * 
-     * Examples:
-     * 
-     *   redirect_to(array(":action" => "show", ":id" => 5))
-     *   redirect_to("http://www.rubyonrails.org")
-     *   redirect_to("/images/screenshot.jpg")
-     *   redirect_to("back")
-     *
-     * @param mixed $options array or string url  
+     *  Redirect the browser to a specified target
+     *
+     *  Redirect the browser to the target specified in $options. This
+     *  parameter can take one of three forms:
+     *  <ul>
+     *    <li>Array: The URL will be generated by calling
+     *      {@link url_for()} with the options.</li>
+     *    <li>String starting with a protocol:// (like http://): Is
+     *      passed straight through as the target for redirection.</li>
+     *    <li>String not containing a protocol: The current protocol
+     *      and host is prepended to the string.</li>
+     *    <li>back: Back to the page that issued the request. Useful
+     *      for forms that are triggered from multiple
+     *      places. Short-hand for redirect_to(request.env["HTTP_REFERER"]) 
+     *   </ul>
+     *
+     *  Examples:
+     *  <ul>
+     *    <li>redirect_to(array(":action" => "show", ":id" => 5))</li>
+     *    <li>redirect_to("http://www.rubyonrails.org")</li>
+     *    <li>redirect_to("/images/screenshot.jpg")</li>
+     *    <li>redirect_to("back")</li>
+     *  </ul>
+     *
+     *  @param mixed $options array or string url  
+     *  @todo <b>FIXME:</b> Make header configurable
      */    
     function redirect_to($options = null) {

trunk/trax/vendor/trax/router.php

@@ -106 +106 @@
      *  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}.
+     *  entry according to
+     *  {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}
+     *  rules.  If a matching route is found, return it any to the caller, and
+     *  also save a copy in {@link $selected_route}; if no matching
+     *  route is found return null.
      *  @param string $url
      *  @uses build_route_regexp()
@@ -115 +117 @@
      *  @uses $routes_count
      *  @uses $selected_route
-     *  @return string[] Selected route. Path is in return['path'],
+     *  @return mixed Matching route or null.  Path is in return['path'],
      *                   params in return['params'],
      */
     function find_route($url) {
+        //error_log('url='.$url);
         // ensure at least one route (the default route) exists
         if($this->routes_count == 0) {
@@ -130 +133 @@
             unset($reg_exp);
             $route_regexp = $this->build_route_regexp($route['path']);
+            //error_log("route regexp=/$route_regexp/");
             if($url == "" && $route_regexp == "") {
+                //error_log('selected');
                 $this->selected_route = $route;
                 break;
             } elseif(preg_match("/$route_regexp/",$url) && $route_regexp != "") {
+                //error_log('selected');
                 $this->selected_route = $route;
                 break;
             } elseif($route['path'] == $this->default_route_path) {
+                //error_log('defaulted');
                 $this->selected_route = $route;
                 break;
             }
         }
-
+        //error_log('selected route='.var_export($this->selected_route,true));
         return $this->selected_route;
     }                                 // function find_route($url)
@@ -148 +155 @@
      *  Build a regular expression that matches a route
      *
-     *  <b>FIXME:</b> Should this method be private?
+     *  @todo <b>FIXME:</b> Should this method be private?
+     *  @todo <b>FIXME:</b> Shouldn't the regexp match be the same as
+     *  for a PHP variable name? '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
      *  @param string $route_path  A route path.
      *  @return string Regular expression that matches the route in
@@ -161 +170 @@
             $route_path = explode("/",$route_path);
         }
-        //        echo "route path:\n";
-        //        var_dump($route_path);
+        //error_log("route path:\n".var_export($route_path,true));
         if(count($route_path) > 0) {
             foreach($route_path as $path_element) {
@@ -175 +183 @@
             }
         }
-
         return $route_regexp;
     }

trunk/trax/vendor/trax/session.php

@@ -172 +172 @@
             $key .= $_SERVER['REMOTE_ADDR'];
         }
+        // error_log('get_hash() returns '.md5($key));
         return md5($key);
     }
@@ -242 +243 @@
      */
     function unset_var($key) {
-        if(self::is_valid_host()) {
+         // error_log('Session::unset_var("'.$key.'")');
+        if(self::is_valid_host()) {
+            // error_log('before unsetting SESSION='.var_export($_SESSION,true));
             unset($_SESSION[self::get_hash()][$key]);
+            // error_log('after unsetting SESSION='.var_export($_SESSION,true));
         }
     }