http/url_map.php

   1 <?php
   2 // Hoplite
   3 // Copyright (c) 2011 Blue Static
   4 //
   5 // This program is free software: you can redistribute it and/or modify it
   6 // under the terms of the GNU General Public License as published by the Free
   7 // Software Foundation, either version 3 of the License, or any later version.
   8 //
   9 // This program is distributed in the hope that it will be useful, but WITHOUT
  10 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  12 // more details.
  13 //
  14 // You should have received a copy of the GNU General Public License along with
  15 // this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 namespace hoplite\http;
  18
  19 /*!
  20   A UrlMap will translate a raw HTTP request into a http\Request object. It does
  21   so by matching the incoming URL to a pattern. For information on the format of
  22   patterns @see ::set_map().
  23 */
  24 class UrlMap
  25 {
  26   /*! @var RootController */
  27   private $controller;
  28
  29   /*! @var array The map of URLs to actions. */
  30   private $map = array();
  31
  32   /*!
  33     Constructs the object with a reference to the RootController.
  34     @param RootController
  35   */
  36   public function __construct(RootController $controller)
  37   {
  38     $this->controller = $controller;
  39   }
  40
  41   /*! Accessor for the RootController */
  42   public function controller() { return $this->controller; }
  43
  44   /*! Gets the URL map */
  45   public function map() { return $this->map; }
  46   /*! @brief Sets the URL map.
  47     The URL map is an associative array of URL prefix patterns to Actions or
  48     file paths containing actions.
  49
  50     The keys can be either a URL prefix or a regular expression.
  51
  52     For URL prefixes, the pattern is matched relative to the root of the entry-
  53     point as specified by the RootController. Patterns should not begin with a
  54     slash. Path fragment parameter extraction can be performed as well. For
  55     example, the pattern 'user/view/{id}' will match a URL like
  56       http://example.com/webapp/user/view/42
  57     And the http\Request's data will have a member called 'id' with value 42.
  58
  59     Regular expression matching is not limited to prefix patterns and can match
  60     any part of the URL (though prefix matching can be enforced using the
  61     the standard regex '^' character). Regex patterns must begin and end with
  62     '/' characters. During evaluation, if any pattern groups are matched, the
  63     resulting matches will be placed in Request data via the 'url_pattern' key.
  64     The following will match the same URL as above:
  65       '/^user\/view\/([0-9]+)/'
  66
  67     Values can be a class name or a relative path to a file that contains an
  68     Action class by the same name, or just the name of an Action class. The
  69     conventions for each are governed by ::LookupAction().
  70
  71     @see ::Evaluate()
  72     @see ::LookupAction()
  73   */
  74   public function set_map(array $map) { $this->map = $map; }
  75
  76   /*! @brief Evalutes the URL map and finds a match.
  77     This will take the incoming URL from the request and will match it against
  78     the patterns in the internal map.
  79
  80     Matching occurs in a linear scan of the URL map, so precedence can be
  81     enforced by ordering rules appropriately. Regular expressions are matched
  82     and URL parameter extraction occurs each time a different rule is evaluated.
  83
  84     This may mutate the request with extracted data if a match is made and
  85     returned.
  86     @see ::set_map() for more information.
  87
  88     If a match is made, this will return the corresponding value for the matched
  89     key in the map. To get an Action object from this, use ::LookupAction().
  90
  91     @return string|NULL A matched value in the ::map() or NULL if no match.
  92   */
  93   public function Evaluate($request_url)
  94   {}
  95
  96   /*! @brief Takes a value from the map and returns an Action object.
  97     The values in the map are either an Action class name or a relative path to
  98     a file containing an Action class.
  99
 100     Mapping to a class requires that the value start with an upper-case letter.
 101
 102     Paths start with a lower-case letter. The last path component will be
 103     transformed into a class name via ::_ClassNameFromFileName(). Note that if
 104     the file extension is not included  in the path, .php will be automatically
 105     appended.
 106
 107     @return Action|NULL The loaded action, or NULL on error.
 108   */
 109   public function LookupAction($map_value)
 110   {}
 111
 112   /*!
 113     Takes a file name and returns the name of an Action class. This uses an
 114     under_score to CamelCase transformation with an 'Action' suffix:
 115       lost_password -> LostPasswordAction
 116
 117     This can be overridden to provide a custom transformation.
 118
 119     @return string Action class name.
 120   */
 121   protected function _ClassNameFromFileName($file_name)
 122   {}
 123 }