* - Matches /foo/Bar explicitly and uses "Baz" as the title
* $router->add( '/help/$1', array( 'title' => 'Help:$1' ) );
* - Matches /help/Foo with "Help:Foo" as the title
- * $router->add( '/help/$1', array( 'title' => 'Help:$1' ) );
- * - Matches
* $router->add( '/$1', array( 'foo' => array( 'value' => 'bar$2' ) );
- * - Matches /Foo and sets 'foo=bar$2' without $2 being replaced
+ * - Matches /Foo and sets 'foo' to 'bar$2' without $2 being replaced
* $router->add( '/$1', array( 'data:foo' => 'bar' ), array( 'callback' => 'functionname' ) );
* - Matches /Foo, adds the key 'foo' with the value 'bar' to the data array
* and calls functionname( &$matches, $data );
*
* Params:
* - In a pattern $1, $2, etc... will be replaced with the relevant contents
- * - If you used a keyed array as a path pattern $key will be replaced with the relevant contents
- * - The default behavior is equivalent to `array( 'title' => '$1' )`, if you don't want the title parameter you can explicitly use `array( 'title' => false )`
- * - You can specify a value that won't have replacements in it using `'foo' => array( 'value' => 'bar' );`
+ * - If you used a keyed array as a path pattern, $key will be replaced with
+ * the relevant contents
+ * - The default behavior is equivalent to `array( 'title' => '$1' )`,
+ * if you don't want the title parameter you can explicitly use `array( 'title' => false )`
+ * - You can specify a value that won't have replacements in it
+ * using `'foo' => array( 'value' => 'bar' );`
*
* Options:
- * - The option keys $1, $2, etc... can be specified to restrict the possible values of that variable.
- * A string can be used for a single value, or an array for multiple.
+ * - The option keys $1, $2, etc... can be specified to restrict the possible values
+ * of that variable. A string can be used for a single value, or an array for multiple.
* - When the option key 'strict' is set (Using addStrict is simpler than doing this directly)
* the path won't have $1 implicitly added to it.
* - The option key 'callback' can specify a callback that will be run when a path is matched.
- * The callback will have the arguments ( &$matches, $data ) and the matches array can be modified.
+ * The callback will have the arguments ( &$matches, $data ) and the matches array can
+ * be modified.
*
* @since 1.19
* @author Daniel Friesen
*/
class PathRouter {
-
+
+ /**
+ * Protected helper to do the actual bulk work of adding a single pattern.
+ * This is in a separate method so that add() can handle the difference between
+ * a single string $path and an array() $path that contains multiple path
+ * patterns each with an associated $key to pass on.
+ */
protected function doAdd( $path, $params, $options, $key = null ) {
+ // Make sure all paths start with a /
if ( $path[0] !== '/' ) {
$path = '/' . $path;
}
}
}
+ // If 'title' is not specified and our path pattern contains a $1
+ // Add a default 'title' => '$1' rule to the parameters.
if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) {
$params['title'] = '$1';
}
+ // If the user explicitly marked 'title' as false then omit it from the matches
if ( isset( $params['title'] ) && $params['title'] === false ) {
unset( $params['title'] );
}
+ // Loop over our parameters and convert basic key => string
+ // patterns into fully descriptive array form
foreach ( $params as $paramName => $paramData ) {
if ( is_string( $paramData ) ) {
- if ( preg_match( '/\$(\d+|key)/', $paramData ) ) {
+ if ( preg_match( '/\$(\d+|key)/u', $paramData ) ) {
$paramArrKey = 'pattern';
} else {
// If there's no replacement use a value instead
}
}
+ // Loop over our options and convert any single value $# restrictions
+ // into an array so we only have to do in_array tests.
foreach ( $options as $optionName => $optionData ) {
- if ( preg_match( '/^\$\d+$/', $optionName ) ) {
+ if ( preg_match( '/^\$\d+$/u', $optionName ) ) {
if ( !is_array( $optionData ) ) {
$options[$optionName] = array( $optionData );
}
}
$pattern = (object)array(
- 'path' => $path,
- 'params' => $params,
+ 'path' => $path,
+ 'params' => $params,
'options' => $options,
- 'key' => $key,
+ 'key' => $key,
);
$pattern->weight = self::makeWeight( $pattern );
$this->patterns[] = $pattern;
$this->add( $path, $params, $options );
}
+ /**
+ * Protected helper to re-sort our patterns so that the most specific
+ * (most heavily weighted) patterns are at the start of the array.
+ */
protected function sortByWeight() {
$weights = array();
foreach( $this->patterns as $key => $pattern ) {
array_multisort( $weights, SORT_DESC, SORT_NUMERIC, $this->patterns );
}
- public static function makeWeight( $pattern ) {
+ protected static function makeWeight( $pattern ) {
# Start with a weight of 0
$weight = 0;
# For each level of the path
foreach( $path as $piece ) {
- if ( preg_match( '/^\$(\d+|key)$/', $piece ) ) {
+ if ( preg_match( '/^\$(\d+|key)$/u', $piece ) ) {
# For a piece that is only a $1 variable add 1 points of weight
$weight += 1;
- } elseif ( preg_match( '/\$(\d+|key)/', $piece ) ) {
+ } elseif ( preg_match( '/\$(\d+|key)/u', $piece ) ) {
# For a piece that simply contains a $1 variable add 2 points of weight
$weight += 2;
} else {
}
foreach ( $pattern->options as $key => $option ) {
- if ( preg_match( '/^\$\d+$/', $key ) ) {
+ if ( preg_match( '/^\$\d+$/u', $key ) ) {
# Add 0.5 for restrictions to values
# This way given two separate "/$2/$1" patterns the
# one with a limited set of $2 values will dominate
* @return Array The array of matches for the path
*/
public function parse( $path ) {
+ // Make sure our patterns are sorted by weight so the most specific
+ // matches are tested first
$this->sortByWeight();
$matches = null;
}
}
+ // We know the difference between null (no matches) and
+ // array() (a match with no data) but our WebRequest caller
+ // expects array() even when we have no matches so return
+ // a array() when we have null
return is_null( $matches ) ? array() : $matches;
}
protected static function extractTitle( $path, $pattern ) {
+ // Convert the path pattern into a regexp we can match with
$regexp = preg_quote( $pattern->path, '#' );
- $regexp = preg_replace( '#\\\\\$1#', '(?P<par1>.*)', $regexp );
- $regexp = preg_replace( '#\\\\\$(\d+)#', '(?P<par$1>.+?)', $regexp );
+ // .* for the $1
+ $regexp = preg_replace( '#\\\\\$1#u', '(?P<par1>.*)', $regexp );
+ // .+ for the rest of the parameter numbers
+ $regexp = preg_replace( '#\\\\\$(\d+)#u', '(?P<par$1>.+?)', $regexp );
$regexp = "#^{$regexp}$#";
$matches = array();
$data = array();
+ // Try to match the path we were asked to parse with our regexp
if ( preg_match( $regexp, $path, $m ) ) {
+ // Ensure that any $# restriction we have set in our {$option}s
+ // matches properly here.
foreach ( $pattern->options as $key => $option ) {
- if ( preg_match( '/^\$\d+$/', $key ) ) {
+ if ( preg_match( '/^\$\d+$/u', $key ) ) {
$n = intval( substr( $key, 1 ) );
- $value = $m["par{$n}"];
+ $value = rawurldecode( $m["par{$n}"] );
if ( !in_array( $value, $option ) ) {
+ // If any restriction does not match return null
+ // to signify that this rule did not match.
return null;
}
}
}
+ // Give our $data array a copy of every $# that was matched
foreach ( $m as $matchKey => $matchValue ) {
- if ( preg_match( '/^par\d+$/', $matchKey ) ) {
+ if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
$n = intval( substr( $matchKey, 3 ) );
- $data['$'.$n] = $matchValue;
+ $data['$'.$n] = rawurldecode( $matchValue );
}
}
+ // If present give our $data array a $key as well
if ( isset( $pattern->key ) ) {
$data['$key'] = $pattern->key;
}
+ // Go through our parameters for this match and add data to our matches and data arrays
foreach ( $pattern->params as $paramName => $paramData ) {
$value = null;
- if ( preg_match( '/^data:/', $paramName ) ) {
+ // Differentiate data: from normal parameters and keep the correct
+ // array key around (ie: foo for data:foo)
+ if ( preg_match( '/^data:/u', $paramName ) ) {
$isData = true;
$key = substr( $paramName, 5 );
} else {
}
if ( isset( $paramData['value'] ) ) {
+ // For basic values just set the raw data as the value
$value = $paramData['value'];
} elseif ( isset( $paramData['pattern'] ) ) {
+ // For patterns we have to make value replacements on the string
$value = $paramData['pattern'];
+ // For each $# match replace any $# within the value
foreach ( $m as $matchKey => $matchValue ) {
- if ( preg_match( '/^par\d+$/', $matchKey ) ) {
+ if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
$n = intval( substr( $matchKey, 3 ) );
- $value = str_replace( '$' . $n, $matchValue, $value );
+ $value = str_replace( '$' . $n, rawurldecode( $matchValue ), $value );
}
}
+ // If a key was set replace any $key within the value
if ( isset( $pattern->key ) ) {
$value = str_replace( '$key', $pattern->key, $value );
}
- if ( preg_match( '/\$(\d+|key)/', $value ) ) {
+ if ( preg_match( '/\$(\d+|key)/u', $value ) ) {
// Still contains $# or $key patterns after replacement
// Seams like we don't have all the data, abort
return null;
}
}
+ // Send things that start with data: to $data, the rest to $matches
if ( $isData ) {
$data[$key] = $value;
} else {
}
}
+ // If this match includes a callback, execute it
if ( isset( $pattern->options['callback'] ) ) {
call_user_func_array( $pattern->options['callback'], array( &$matches, $data ) );
}
} else {
+ // Our regexp didn't match, return null to signify no match.
return null;
}
+ // Fall through, everything went ok, return our matches array
return $matches;
}