Class Horde_Routes_Mapper

Description

The mapper class handles URL generation and recognition for web applications

The mapper class is built by handling associated arrays of information and passing associated arrays back to the application for it to handle and dispatch the appropriate scripts.

Located in /Routes/lib/Horde/Routes/Mapper.php (line 24)


	
			
Variable Summary
 boolean $alwaysScan
 boolean $appendSlash
 callback $controllerScan
 boolean $debug
 string $decodeErrors
 string $directory
 string $domainMatch
 string $encoding
 array $environ
 boolean $explicit
 array $matchList
 array $maxKeys
 array $minKeys
 null|string $prefix
 array $routeNames
 boolean $subDomains
 array $urlCache
 boolean $_createdGens
 boolean $_createdRegs
 array $_gendict
 array $_keysortTmp
 string $_regPrefix
Method Summary
 Horde_Routes_Mapper __construct ([ $kargs = array()])
 void connect (mixed $first, [mixed $second = null], [mixed $third = null])
 void createRegs ([array $clist = null])
 null|string generate ([array $kargs = array()])
 void match (string $url, array|null 1)
 void resource (string $memberName, string $collectionName, [array $kargs = array()])
 void routematch (string $url, array|null 1)
 array _arrayUnion (array $a, array $b)
 void _cmp (integer|float $a, integer|flot $b, integer 2)
 void _createGens ()
 integer _keycmp (array $a, array $b)
 void _keysort ( &$array, array $array)
 null|array _match (string $url)
 $options _requirementsFor ( $meth, array $options, string $method)
 string _stripSlashes (string $name)
 array _swap (array $dct, array $newdct)
Variables
boolean $alwaysScan (line 48)

Call controllerScan callback before every route match?

  • access: public
boolean $appendSlash = false (line 78)

Append trailing slash ('/') to generated routes?

  • access: public
callback $controllerScan (line 36)

Callback function used to get array of controller names

  • access: public
boolean $debug = false (line 60)

Collect debug information during route match?

  • access: public
string $decodeErrors = 'ignore' (line 114)

What to do on decoding errors? 'ignore' or 'replace'

  • access: public
string $directory (line 42)

Path to controller directory passed to controllerScan function

  • access: public
string $domainMatch = '[^\.\/]+?\.[^\.\/]+' (line 120)

Partial regexp used to match domain part of the end of URLs to match

  • access: public
string $encoding = 'utf-8' (line 108)

Encoding of routes URLs (not yet supported)

  • access: public
array $environ = array() (line 30)

Filtered request environment with keys like SCRIPT_NAME

  • access: public
boolean $explicit (line 54)

Disable route memory and implicit defaults?

  • access: public
array $matchList = array() (line 90)

Array of connected routes

  • access: public
array $maxKeys = array() (line 127)

Array of all connected routes, indexed by the serialized array of all keys that each route could utilize.

  • access: public
array $minKeys = array() (line 134)

Array of all connected routes, indexed by the serialized array of the minimum keys that each route needs.

  • access: public
null|string $prefix = null (line 84)

Prefix to strip during matching and to append during generation

  • access: public
array $routeNames = array() (line 96)

Array of connected named routes, indexed by name

  • access: public
boolean $subDomains = false (line 66)

Use sub-domain support?

  • access: public
array $subDomainsIgnore = array() (line 72)

Array of sub-domains to ignore if using sub-domain support

  • access: public
array $urlCache = array() (line 102)

Cache of URLs used in generate()

  • access: public
Horde_Routes_Utils $utils (line 140)

Utility functions like urlFor() and redirectTo() for this Mapper

  • access: public
boolean $_createdGens = false (line 152)

Have generation hashes been created for all connected routes?

  • access: protected
boolean $_createdRegs = false (line 146)

Have regular expressions been created for all connected routes?

  • access: protected
array $_gendict (line 158)

Generation hashes created for all connected routes

  • access: protected
array $_keysortTmp (line 164)

Temporary variable used to pass array of keys into _keysort() callback

  • access: protected
string $_regPrefix = null (line 170)

Regular expression generated to match after the prefix

  • access: protected
Methods
Constructor __construct (line 196)

Constructor.

Keyword arguments ($kargs): ``controllerScan`` (callback) Function to return an array of valid controllers

``redirect`` (callback) Function to perform a redirect for Horde_Routes_Utils->redirectTo()

``directory`` (string) Path to the directory that will be passed to the controllerScan callback

``alwaysScan`` (boolean) Should the controllerScan callback be called before every URL match?

``explicit`` (boolean) Should routes be connected with the implicit defaults of array('controller'=>'content', 'action'=>'index', 'id'=>null)? When set to True, these will not be added to route connections.

  • access: public
Horde_Routes_Mapper __construct ([ $kargs = array()])
  • $kargs
connect (line 236)

Create and connect a new Route to the Mapper.

Usage: $m = new Horde_Routes_Mapper(); $m->connect(':controller/:action/:id'); $m->connect('date/:year/:month/:day', array('controller' => "blog", 'action' => 'view'); $m->connect('archives/:page', array('controller' => 'blog', 'action' => 'by_page', ' requirements' => array('page' => '\d{1,2}'))); $m->connect('category_list', 'archives/category/:section', array('controller' => 'blog', 'action' => 'category', 'section' => 'home', 'type' => 'list')); $m->connect('home', '', array('controller' => 'blog', 'action' => 'view', 'section' => 'home'));

  • access: public
void connect (mixed $first, [mixed $second = null], [mixed $third = null])
  • mixed $first: First argument in vargs, see usage above.
  • mixed $second: Second argument in varags
  • mixed $third: Third argument in varargs
createRegs (line 383)

Creates the regexes for all connected routes

  • access: public
void createRegs ([array $clist = null])
  • array $clist: controller list, controller_scan will be used otherwise
generate (line 523)

Generates the URL from a given set of keywords Returns the URL text, or null if no URL could be generated.

Usage: $m->generate(array('controller' => 'content', 'action' => 'view', 'id' => 10));

  • return: URL text or null
  • access: public
null|string generate ([array $kargs = array()])
  • array $kargs: Keyword arguments (key/value pairs)
match (line 475)

Match a URL against one of the routes contained.

It will return null if no valid match is found.

Usage: $resultdict = $m->match('/joe/sixpack');

  • access: public
void match (string $url, array|null 1)
  • string $url: URL to match
  • array|null 1: Array if matched, otherwise null
resource (line 781)

Generate routes for a controller resource

The $memberName name should be the appropriate singular version of the resource given your locale and used with members of the collection.

The $collectionName name will be used to refer to the resource collection methods and should be a plural version of the $memberName argument. By default, the $memberName name will also be assumed to map to a controller you create.

The concept of a web resource maps somewhat directly to 'CRUD' operations. The overlying things to keep in mind is that mapping a resource is about handling creating, viewing, and editing that resource.

All keyword arguments ($kargs) are optional.

``controller`` If specified in the keyword args, the controller will be the actual controller used, but the rest of the naming conventions used for the route names and URL paths are unchanged.

``collection`` Additional action mappings used to manipulate/view the entire set of resources provided by the controller.

Example::

$map->resource('message', 'messages', array('collection' => array('rss' => 'GET)));

  • GET /message;rss (maps to the rss action)
  • also adds named route "rss_message"
``member`` Additional action mappings used to access an individual 'member' of this controllers resources.

Example::

$map->resource('message', 'messages', array('member' => array('mark' => 'POST')));

  • POST /message/1;mark (maps to the mark action)
  • also adds named route "mark_message"
``new`` Action mappings that involve dealing with a new member in the controller resources.

Example::

$map->resource('message', 'messages', array('new' => array('preview' => 'POST')));

  • POST /message/new;preview (maps to the preview action)
  • also adds a url named "preview_new_message"
``pathPrefix`` Prepends the URL path for the Route with the pathPrefix given. This is most useful for cases where you want to mix resources or relations between resources.

``namePrefix`` Perpends the route names that are generated with the namePrefix given. Combined with the pathPrefix option, it's easy to generate route names and paths that represent resources that are in relations.

Example::

map.resource('message', 'messages', array('controller' => 'categories', 'pathPrefix' => '/category/:category_id', 'namePrefix' => 'category_')));

  • GET /category/7/message/1
  • has named route "category_message"
``parentResource`` An assoc. array containing information about the parent resource, for creating a nested resource. It should contain the ``$memberName`` and ``collectionName`` of the parent resource. This assoc. array will be available via the associated ``Route`` object which can be accessed during a request via ``request.environ['routes.route']``

If ``parentResource`` is supplied and ``pathPrefix`` isn't, ``pathPrefix`` will be generated from ``parentResource`` as "<parent collection name>/:<parent member name>_id".

If ``parentResource`` is supplied and ``namePrefix`` isn't, ``namePrefix`` will be generated from ``parentResource`` as "<parent member name>_".

Example::

$m = new Horde_Routes_Mapper(); $utils = $m->utils;

$m->resource('location', 'locations', array('parentResource' => array('memberName' => 'region', 'collectionName' => 'regions'))));

  • pathPrefix is "regions/:region_id"
  • namePrefix is "region_"
$utils->urlFor('region_locations', array('region_id'=>13));
  • '/regions/13/locations'
$utils->urlFor('region_new_location', array('region_id'=>13));
  • '/regions/13/locations/new'
$utils->urlFor('region_location', array('region_id'=>13, 'id'=>60));
  • '/regions/13/locations/60'
$utils->urlFor('region_edit_location', array('region_id'=>13, 'id'=>60));
  • '/regions/13/locations/60;edit'
Overriding generated ``pathPrefix``::

$m = new Horde_Routes_Mapper(); $utils = new Horde_Routes_Utils();

$m->resource('location', 'locations', array('parentResource' => array('memberName' => 'region', 'collectionName' => 'regions'), 'pathPrefix' => 'areas/:area_id')));

  • name prefix is "region_"
$utils->urlFor('region_locations', array('area_id'=>51));
  • '/areas/51/locations'
Overriding generated ``namePrefix``::

$m = new Horde_Routes_Mapper $m->resource('location', 'locations', array('parentResource' => array('memberName' => 'region', 'collectionName' => 'regions'), 'namePrefix' => '')));

  • pathPrefix is "regions/:region_id"
$utils->urlFor('locations', array('region_id'=>51));
  • '/regions/51/locations'

  • access: public
void resource (string $memberName, string $collectionName, [array $kargs = array()])
  • string $memberName: Singular version of the resource name
  • string $collectionName: Collection name (plural of $memberName)
  • array $kargs: Keyword arguments (see above)
routematch (line 502)

Match a URL against one of the routes contained.

It will return null if no valid match is found, otherwise a result dict (array) and a route object is returned.

Usage: list($resultdict, $resultobj) = $m->match('/joe/sixpack');

  • access: public
void routematch (string $url, array|null 1)
  • string $url: URL to match
  • array|null 1: Array if matched, otherwise null
_arrayUnion (line 1110)

Create a union of two arrays.

  • return: Union of $a and $b
  • access: protected
array _arrayUnion (array $a, array $b)
  • array $a: First array
  • array $b: Second array
_cmp (line 1122)

Equivalent of Python's cmp() function.

  • access: protected
void _cmp (integer|float $a, integer|flot $b, integer 2)
  • integer|float $a: First item to compare
  • integer|flot $b: Second item to compare
  • integer 2: Result of comparison
_createGens (line 307)

Create the generation hashes (arrays) for route lookups

  • access: protected
void _createGens ()
_keycmp (line 1063)

Compare two Horde_Route_Routes objects by their keys against the instance variable $keysortTmp. Used by _keysort().

  • access: protected
integer _keycmp (array $a, array $b)
  • array $a: First dict (assoc. array)
  • array $b: Second dict
_keysort (line 1016)

Sort an array of Horde_Routes_Routes to using _keycmp() for the comparision to order them ideally for matching.

An unfortunate property of PHP's usort() is that if two members compare equal, their order in the sorted array is undefined (see PHP manual). This is unsuitable for us because the order that the routes were connected to the mapper is significant.

Uses this method uses merge sort algorithm based on the comments in http://www.php.net/usort

  • access: protected
void _keysort ( &$array, array $array)
  • array $array: Array Horde_Routes_Route objects to sort (by reference)
  • &$array
_match (line 416)

Internal Route matcher

Matches a URL against a route, and returns a tuple (array) of the match dict (array) and the route object if a match is successful, otherwise it returns null.

  • return: Match data if matched, otherwise null
  • access: protected
null|array _match (string $url)
  • string $url: URL to match
_requirementsFor (line 972)

Returns a new dict to be used for all route creation as the route options.

$options _requirementsFor ( $meth, array $options, string $method)
  • string $method: Request method ('get', 'post', etc.) or 'any'
  • array $options: Assoc. array to populate with 'conditions' key
  • $meth
_stripSlashes (line 1139)

Trims slashes from the beginning or end of a part/URL.

  • return: Part or URL with begin/end slashes removed
  • access: protected
string _stripSlashes (string $name)
  • string $name: Part or URL with slash at begin/end
_swap (line 989)

Swap the keys and values in the dict, and uppercase the values from the dict during the swap.

array _swap (array $dct, array $newdct)
  • array $dct: Input dict (assoc. array)
  • array $newdct: Output dict to populate

Documentation generated on Sun, 30 Jan 2011 05:19:31 +0000 by phpDocumentor 1.4.3