includes/PathRouter.php

   1 <?php
   2 /**
   3  * PathRouter class.
   4  * This class can take patterns such as /wiki/$1 and use them to
   5  * parse query parameters out of REQUEST_URI paths.
   6  *
   7  * $router->add( "/wiki/$1" );
   8  *   - Matches /wiki/Foo style urls and extracts the title
   9  * $router->add( array( 'edit' => "/edit/$1" ), array( 'action' => '$key' ) );
  10  *   - Matches /edit/Foo style urls and sets action=edit
  11  * $router->add( '/$2/$1',
  12  *   array( 'variant' => '$2' ),
  13  *   array( '$2' => array( 'zh-hant', 'zh-hans' )
  14  * );
  15  *   - Matches /zh-hant/Foo or /zh-hans/Foo
  16  * $router->addStrict( "/foo/Bar", array( 'title' => 'Baz' ) );
  17  *   - Matches /foo/Bar explicitly and uses "Baz" as the title
  18  * $router->add( '/help/$1', array( 'title' => 'Help:$1' ) );
  19  *   - Matches /help/Foo with "Help:Foo" as the title
  20  * $router->add( '/help/$1', array( 'title' => 'Help:$1' ) );
  21  *   - Matches
  22  * $router->add( '/$1', array( 'foo' => array( 'value' => 'bar$2' ) );
  23  *   - Matches /Foo and sets 'foo=bar$2' without $2 being replaced
  24  * $router->add( '/$1', array( 'data:foo' => 'bar' ), array( 'callback' => 'functionname' ) );
  25  *   - Matches /Foo, adds the key 'foo' with the value 'bar' to the data array
  26  *     and calls functionname( &$matches, $data );
  27  *
  28  * Path patterns:
  29  *   - Paths may contain $# patterns such as $1, $2, etc...
  30  *   - $1 will match 0 or more while the rest will match 1 or more
  31  *   - Unless you use addStrict "/wiki" and "/wiki/" will be expanded to "/wiki/$1"
  32  *
  33  * Params:
  34  *   - In a pattern $1, $2, etc... will be replaced with the relevant contents
  35  *   - If you used a keyed array as a path pattern $key will be replaced with the relevant contents
  36  *   - The default behavior is equivalent to `array( 'title' => '$1' )`, if you don't want the title parameter you can explicitly use `array( 'title' => false )`
  37  *   - You can specify a value that won't have replacements in it using `'foo' => array( 'value' => 'bar' );`
  38  *
  39  * Options:
  40  *   - The option keys $1, $2, etc... can be specified to restrict the possible values of that variable.
  41  *     A string can be used for a single value, or an array for multiple.
  42  *   - When the option key 'strict' is set (Using addStrict is simpler than doing this directly)
  43  *     the path won't have $1 implicitly added to it.
  44  *   - The option key 'callback' can specify a callback that will be run when a path is matched.
  45  *     The callback will have the arguments ( &$matches, $data ) and the matches array can be modified.
  46  *
  47  * @since 1.19
  48  * @author Daniel Friesen
  49  */
  50 class PathRouter {
  51
  52         protected function doAdd( $path, $params, $options, $key = null ) {
  53                 if ( $path[0] !== '/' ) {
  54                         $path = '/' . $path;
  55                 }
  56
  57                 if ( !isset( $options['strict'] ) || !$options['strict'] ) {
  58                         // Unless this is a strict path make sure that the path has a $1
  59                         if ( strpos( $path, '$1' ) === false ) {
  60                                 if ( substr( $path, -1 ) !== '/' ) {
  61                                         $path .= '/';
  62                                 }
  63                                 $path .= '$1';
  64                         }
  65                 }
  66
  67                 if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) {
  68                         $params['title'] = '$1';
  69                 }
  70                 if ( isset( $params['title'] ) && $params['title'] === false ) {
  71                         unset( $params['title'] );
  72                 }
  73
  74                 foreach ( $params as $paramName => $paramData ) {
  75                         if ( is_string( $paramData ) ) {
  76                                 if ( preg_match( '/\$(\d+|key)/', $paramData ) ) {
  77                                         $paramArrKey = 'pattern';
  78                                 } else {
  79                                         // If there's no replacement use a value instead
  80                                         // of a pattern for a little more efficiency
  81                                         $paramArrKey = 'value';
  82                                 }
  83                                 $params[$paramName] = array(
  84                                         $paramArrKey => $paramData
  85                                 );
  86                         }
  87                 }
  88
  89                 foreach ( $options as $optionName => $optionData ) {
  90                         if ( preg_match( '/^\$\d+$/', $optionName ) ) {
  91                                 if ( !is_array( $optionData ) ) {
  92                                         $options[$optionName] = array( $optionData );
  93                                 }
  94                         }
  95                 }
  96
  97                 $pattern = (object)array(
  98                         'path' => $path,
  99                         'params' => $params,
 100                         'options' => $options,
 101                         'key' => $key,
 102                 );
 103                 $pattern->weight = self::makeWeight( $pattern );
 104                 $this->patterns[] = $pattern;
 105         }
 106
 107         /**
 108          * Add a new path pattern to the path router
 109          *
 110          * @param $path The path pattern to add
 111          * @param $params The params for this path pattern
 112          * @param $options The options for this path pattern
 113          */
 114         public function add( $path, $params = array(), $options = array() ) {
 115                 if ( is_array( $path ) ) {
 116                         foreach ( $path as $key => $onePath ) {
 117                                 $this->doAdd( $onePath, $params, $options, $key );
 118                         }
 119                 } else {
 120                         $this->doAdd( $path, $params, $options );
 121                 }
 122         }
 123
 124         /**
 125          * Add a new path pattern to the path router with the strict option on
 126          * @see self::add
 127          */
 128         public function addStrict( $path, $params = array(), $options = array() ) {
 129                 $options['strict'] = true;
 130                 $this->add( $path, $params, $options );
 131         }
 132
 133         protected function sortByWeight() {
 134                 $weights = array();
 135                 foreach( $this->patterns as $key => $pattern ) {
 136                         $weights[$key] = $pattern->weight;
 137                 }
 138                 array_multisort( $weights, SORT_DESC, SORT_NUMERIC, $this->patterns );
 139         }
 140
 141         public static function makeWeight( $pattern ) {
 142                 # Start with a weight of 0
 143                 $weight = 0;
 144
 145                 // Explode the path to work with
 146                 $path = explode( '/', $pattern->path );
 147
 148                 # For each level of the path
 149                 foreach( $path as $piece ) {
 150                         if ( preg_match( '/^\$(\d+|key)$/', $piece ) ) {
 151                                 # For a piece that is only a $1 variable add 1 points of weight
 152                                 $weight += 1;
 153                         } elseif ( preg_match( '/\$(\d+|key)/', $piece ) ) {
 154                                 # For a piece that simply contains a $1 variable add 2 points of weight
 155                                 $weight += 2;
 156                         } else {
 157                                 # For a solid piece add a full 3 points of weight
 158                                 $weight += 3;
 159                         }
 160                 }
 161
 162                 foreach ( $pattern->options as $key => $option ) {
 163                         if ( preg_match( '/^\$\d+$/', $key ) ) {
 164                                 # Add 0.5 for restrictions to values
 165                                 # This way given two separate "/$2/$1" patterns the
 166                                 # one with a limited set of $2 values will dominate
 167                                 # the one that'll match more loosely
 168                                 $weight += 0.5;
 169                         }
 170                 }
 171
 172                 return $weight;
 173         }
 174
 175         /**
 176          * Parse a path and return the query matches for the path
 177          *
 178          * @param $path The path to parse
 179          * @return Array The array of matches for the path
 180          */
 181         public function parse( $path ) {
 182                 $this->sortByWeight();
 183
 184                 $matches = null;
 185
 186                 foreach ( $this->patterns as $pattern ) {
 187                         $matches = self::extractTitle( $path, $pattern );
 188                         if ( !is_null( $matches ) ) {
 189                                 break;
 190                         }
 191                 }
 192
 193                 return is_null( $matches ) ? array() : $matches;
 194         }
 195
 196         protected static function extractTitle( $path, $pattern ) {
 197                 $regexp = preg_quote( $pattern->path, '#' );
 198                 $regexp = preg_replace( '#\\\\\$1#', '(?P<par1>.*)', $regexp );
 199                 $regexp = preg_replace( '#\\\\\$(\d+)#', '(?P<par$1>.+?)', $regexp );
 200                 $regexp = "#^{$regexp}$#";
 201
 202                 $matches = array();
 203                 $data = array();
 204
 205                 if ( preg_match( $regexp, $path, $m ) ) {
 206                         foreach ( $pattern->options as $key => $option ) {
 207                                 if ( preg_match( '/^\$\d+$/', $key ) ) {
 208                                         $n = intval( substr( $key, 1 ) );
 209                                         $value = $m["par{$n}"];
 210                                         if ( !in_array( $value, $option ) ) {
 211                                                 return null;
 212                                         }
 213                                 }
 214                         }
 215
 216                         foreach ( $m as $matchKey => $matchValue ) {
 217                                 if ( preg_match( '/^par\d+$/', $matchKey ) ) {
 218                                         $n = intval( substr( $matchKey, 3 ) );
 219                                         $data['$'.$n] = $matchValue;
 220                                 }
 221                         }
 222
 223                         foreach ( $pattern->params as $paramName => $paramData ) {
 224                                 $value = null;
 225                                 if ( preg_match( '/^data:/', $paramName ) ) {
 226                                         $isData = true;
 227                                         $key = substr( $paramName, 5 );
 228                                 } else {
 229                                         $isData = false;
 230                                         $key = $paramName;
 231                                 }
 232
 233                                 if ( isset( $paramData['value'] ) ) {
 234                                         $value = $paramData['value'];
 235                                 } elseif ( isset( $paramData['pattern'] ) ) {
 236                                         $value = $paramData['pattern'];
 237                                         foreach ( $m as $matchKey => $matchValue ) {
 238                                                 if ( preg_match( '/^par\d+$/', $matchKey ) ) {
 239                                                         $n = intval( substr( $matchKey, 3 ) );
 240                                                         $value = str_replace( '$' . $n, $matchValue, $value );
 241                                                 }
 242                                         }
 243                                         if ( isset( $pattern->key ) ) {
 244                                                 $value = str_replace( '$key', $pattern->key, $value );
 245                                         }
 246                                         if ( preg_match( '/\$(\d+|key)/', $value ) ) {
 247                                                 // Still contains $# or $key patterns after replacement
 248                                                 // Seams like we don't have all the data, abort
 249                                                 return null;
 250                                         }
 251                                 }
 252
 253                                 if ( $isData ) {
 254                                         $data[$key] = $value;
 255                                 } else {
 256                                         $matches[$key] = $value;
 257                                 }
 258                         }
 259
 260                         if ( isset( $pattern->options['callback'] ) ) {
 261                                 call_user_func_array( $pattern->options['callback'], array( &$matches, $data ) );
 262                         }
 263                 } else {
 264                         return null;
 265                 }
 266                 return $matches;
 267         }
 268
 269 }