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( '/$1', array( 'foo' => array( 'value' => 'bar$2' ) );
  21  *   - Matches /Foo and sets 'foo' to 'bar$2' without $2 being replaced
  22  * $router->add( '/$1', array( 'data:foo' => 'bar' ), array( 'callback' => 'functionname' ) );
  23  *   - Matches /Foo, adds the key 'foo' with the value 'bar' to the data array
  24  *     and calls functionname( &$matches, $data );
  25  *
  26  * Path patterns:
  27  *   - Paths may contain $# patterns such as $1, $2, etc...
  28  *   - $1 will match 0 or more while the rest will match 1 or more
  29  *   - Unless you use addStrict "/wiki" and "/wiki/" will be expanded to "/wiki/$1"
  30  *
  31  * Params:
  32  *   - In a pattern $1, $2, etc... will be replaced with the relevant contents
  33  *   - If you used a keyed array as a path pattern, $key will be replaced with
  34  *     the relevant contents
  35  *   - The default behavior is equivalent to `array( 'title' => '$1' )`,
  36  *     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
  38  *     using `'foo' => array( 'value' => 'bar' );`
  39  *
  40  * Options:
  41  *   - The option keys $1, $2, etc... can be specified to restrict the possible values
  42  *     of that variable. A string can be used for a single value, or an array for multiple.
  43  *   - When the option key 'strict' is set (Using addStrict is simpler than doing this directly)
  44  *     the path won't have $1 implicitly added to it.
  45  *   - The option key 'callback' can specify a callback that will be run when a path is matched.
  46  *     The callback will have the arguments ( &$matches, $data ) and the matches array can
  47  *     be modified.
  48  *
  49  * @since 1.19
  50  * @author Daniel Friesen
  51  */
  52 class PathRouter {
  53
  54         /**
  55          * @var array
  56          */
  57         private $patterns = array();
  58
  59         /**
  60          * Protected helper to do the actual bulk work of adding a single pattern.
  61          * This is in a separate method so that add() can handle the difference between
  62          * a single string $path and an array() $path that contains multiple path
  63          * patterns each with an associated $key to pass on.
  64          * @param $path string
  65          * @param $params array
  66          * @param $options array
  67          * @param $key null|string
  68          */
  69         protected function doAdd( $path, $params, $options, $key = null ) {
  70                 // Make sure all paths start with a /
  71                 if ( $path[0] !== '/' ) {
  72                         $path = '/' . $path;
  73                 }
  74
  75                 if ( !isset( $options['strict'] ) || !$options['strict'] ) {
  76                         // Unless this is a strict path make sure that the path has a $1
  77                         if ( strpos( $path, '$1' ) === false ) {
  78                                 if ( substr( $path, -1 ) !== '/' ) {
  79                                         $path .= '/';
  80                                 }
  81                                 $path .= '$1';
  82                         }
  83                 }
  84
  85                 // If 'title' is not specified and our path pattern contains a $1
  86                 // Add a default 'title' => '$1' rule to the parameters.
  87                 if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) {
  88                         $params['title'] = '$1';
  89                 }
  90                 // If the user explicitly marked 'title' as false then omit it from the matches
  91                 if ( isset( $params['title'] ) && $params['title'] === false ) {
  92                         unset( $params['title'] );
  93                 }
  94
  95                 // Loop over our parameters and convert basic key => string
  96                 // patterns into fully descriptive array form
  97                 foreach ( $params as $paramName => $paramData ) {
  98                         if ( is_string( $paramData ) ) {
  99                                 if ( preg_match( '/\$(\d+|key)/u', $paramData ) ) {
 100                                         $paramArrKey = 'pattern';
 101                                 } else {
 102                                         // If there's no replacement use a value instead
 103                                         // of a pattern for a little more efficiency
 104                                         $paramArrKey = 'value';
 105                                 }
 106                                 $params[$paramName] = array(
 107                                         $paramArrKey => $paramData
 108                                 );
 109                         }
 110                 }
 111
 112                 // Loop over our options and convert any single value $# restrictions
 113                 // into an array so we only have to do in_array tests.
 114                 foreach ( $options as $optionName => $optionData ) {
 115                         if ( preg_match( '/^\$\d+$/u', $optionName ) ) {
 116                                 if ( !is_array( $optionData ) ) {
 117                                         $options[$optionName] = array( $optionData );
 118                                 }
 119                         }
 120                 }
 121
 122                 $pattern = (object)array(
 123                         'path'    => $path,
 124                         'params'  => $params,
 125                         'options' => $options,
 126                         'key'     => $key,
 127                 );
 128                 $pattern->weight = self::makeWeight( $pattern );
 129                 $this->patterns[] = $pattern;
 130         }
 131
 132         /**
 133          * Add a new path pattern to the path router
 134          *
 135          * @param $path string|array The path pattern to add
 136          * @param $params array The params for this path pattern
 137          * @param $options array The options for this path pattern
 138          */
 139         public function add( $path, $params = array(), $options = array() ) {
 140                 if ( is_array( $path ) ) {
 141                         foreach ( $path as $key => $onePath ) {
 142                                 $this->doAdd( $onePath, $params, $options, $key );
 143                         }
 144                 } else {
 145                         $this->doAdd( $path, $params, $options );
 146                 }
 147         }
 148
 149         /**
 150          * Add a new path pattern to the path router with the strict option on
 151          * @see self::add
 152          * @param $path string|array
 153          * @param $params array
 154          * @param $options array
 155          */
 156         public function addStrict( $path, $params = array(), $options = array() ) {
 157                 $options['strict'] = true;
 158                 $this->add( $path, $params, $options );
 159         }
 160
 161         /**
 162          * Protected helper to re-sort our patterns so that the most specific
 163          * (most heavily weighted) patterns are at the start of the array.
 164          */
 165         protected function sortByWeight() {
 166                 $weights = array();
 167                 foreach( $this->patterns as $key => $pattern ) {
 168                         $weights[$key] = $pattern->weight;
 169                 }
 170                 array_multisort( $weights, SORT_DESC, SORT_NUMERIC, $this->patterns );
 171         }
 172
 173         /**
 174          * @param $pattern object
 175          * @return float|int
 176          */
 177         protected static function makeWeight( $pattern ) {
 178                 # Start with a weight of 0
 179                 $weight = 0;
 180
 181                 // Explode the path to work with
 182                 $path = explode( '/', $pattern->path );
 183
 184                 # For each level of the path
 185                 foreach( $path as $piece ) {
 186                         if ( preg_match( '/^\$(\d+|key)$/u', $piece ) ) {
 187                                 # For a piece that is only a $1 variable add 1 points of weight
 188                                 $weight += 1;
 189                         } elseif ( preg_match( '/\$(\d+|key)/u', $piece ) ) {
 190                                 # For a piece that simply contains a $1 variable add 2 points of weight
 191                                 $weight += 2;
 192                         } else {
 193                                 # For a solid piece add a full 3 points of weight
 194                                 $weight += 3;
 195                         }
 196                 }
 197
 198                 foreach ( $pattern->options as $key => $option ) {
 199                         if ( preg_match( '/^\$\d+$/u', $key ) ) {
 200                                 # Add 0.5 for restrictions to values
 201                                 # This way given two separate "/$2/$1" patterns the
 202                                 # one with a limited set of $2 values will dominate
 203                                 # the one that'll match more loosely
 204                                 $weight += 0.5;
 205                         }
 206                 }
 207
 208                 return $weight;
 209         }
 210
 211         /**
 212          * Parse a path and return the query matches for the path
 213          *
 214          * @param $path string The path to parse
 215          * @return Array The array of matches for the path
 216          */
 217         public function parse( $path ) {
 218                 // Make sure our patterns are sorted by weight so the most specific
 219                 // matches are tested first
 220                 $this->sortByWeight();
 221
 222                 $matches = null;
 223
 224                 foreach ( $this->patterns as $pattern ) {
 225                         $matches = self::extractTitle( $path, $pattern );
 226                         if ( !is_null( $matches ) ) {
 227                                 break;
 228                         }
 229                 }
 230
 231                 // We know the difference between null (no matches) and
 232                 // array() (a match with no data) but our WebRequest caller
 233                 // expects array() even when we have no matches so return
 234                 // a array() when we have null
 235                 return is_null( $matches ) ? array() : $matches;
 236         }
 237
 238         /**
 239          * @param $path string
 240          * @param $pattern string
 241          * @return array|null
 242          */
 243         protected static function extractTitle( $path, $pattern ) {
 244                 // Convert the path pattern into a regexp we can match with
 245                 $regexp = preg_quote( $pattern->path, '#' );
 246                 // .* for the $1
 247                 $regexp = preg_replace( '#\\\\\$1#u', '(?P<par1>.*)', $regexp );
 248                 // .+ for the rest of the parameter numbers
 249                 $regexp = preg_replace( '#\\\\\$(\d+)#u', '(?P<par$1>.+?)', $regexp );
 250                 $regexp = "#^{$regexp}$#";
 251
 252                 $matches = array();
 253                 $data = array();
 254
 255                 // Try to match the path we were asked to parse with our regexp
 256                 if ( preg_match( $regexp, $path, $m ) ) {
 257                         // Ensure that any $# restriction we have set in our {$option}s
 258                         // matches properly here.
 259                         foreach ( $pattern->options as $key => $option ) {
 260                                 if ( preg_match( '/^\$\d+$/u', $key ) ) {
 261                                         $n = intval( substr( $key, 1 ) );
 262                                         $value = rawurldecode( $m["par{$n}"] );
 263                                         if ( !in_array( $value, $option ) ) {
 264                                                 // If any restriction does not match return null
 265                                                 // to signify that this rule did not match.
 266                                                 return null;
 267                                         }
 268                                 }
 269                         }
 270
 271                         // Give our $data array a copy of every $# that was matched
 272                         foreach ( $m as $matchKey => $matchValue ) {
 273                                 if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
 274                                         $n = intval( substr( $matchKey, 3 ) );
 275                                         $data['$'.$n] = rawurldecode( $matchValue );
 276                                 }
 277                         }
 278                         // If present give our $data array a $key as well
 279                         if ( isset( $pattern->key ) ) {
 280                                 $data['$key'] = $pattern->key;
 281                         }
 282
 283                         // Go through our parameters for this match and add data to our matches and data arrays
 284                         foreach ( $pattern->params as $paramName => $paramData ) {
 285                                 $value = null;
 286                                 // Differentiate data: from normal parameters and keep the correct
 287                                 // array key around (ie: foo for data:foo)
 288                                 if ( preg_match( '/^data:/u', $paramName ) ) {
 289                                         $isData = true;
 290                                         $key = substr( $paramName, 5 );
 291                                 } else {
 292                                         $isData = false;
 293                                         $key = $paramName;
 294                                 }
 295
 296                                 if ( isset( $paramData['value'] ) ) {
 297                                         // For basic values just set the raw data as the value
 298                                         $value = $paramData['value'];
 299                                 } elseif ( isset( $paramData['pattern'] ) ) {
 300                                         // For patterns we have to make value replacements on the string
 301                                         $value = $paramData['pattern'];
 302                                         $replacer = new PathRouterPatternReplacer;
 303                                         $replacer->params = $m;
 304                                         if ( isset( $pattern->key ) ) {
 305                                                 $replacer->key = $pattern->key;
 306                                         }
 307                                         $value = $replacer->replace( $value );
 308                                         if ( $value === false ) {
 309                                                 // Pattern required data that wasn't available, abort
 310                                                 return null;
 311                                         }
 312                                 }
 313
 314                                 // Send things that start with data: to $data, the rest to $matches
 315                                 if ( $isData ) {
 316                                         $data[$key] = $value;
 317                                 } else {
 318                                         $matches[$key] = $value;
 319                                 }
 320                         }
 321
 322                         // If this match includes a callback, execute it
 323                         if ( isset( $pattern->options['callback'] ) ) {
 324                                 call_user_func_array( $pattern->options['callback'], array( &$matches, $data ) );
 325                         }
 326                 } else {
 327                         // Our regexp didn't match, return null to signify no match.
 328                         return null;
 329                 }
 330                 // Fall through, everything went ok, return our matches array
 331                 return $matches;
 332         }
 333
 334 }
 335
 336 class PathRouterPatternReplacer {
 337
 338         public $key, $params, $error;
 339
 340         /**
 341          * Replace keys inside path router patterns with text.
 342          * We do this inside of a replacement callback because after replacement we can't tell the
 343          * difference between a $1 that was not replaced and a $1 that was part of
 344          * the content a $1 was replaced with.
 345          * @param $value string
 346          * @return string
 347          */
 348         public function replace( $value ) {
 349                 $this->error = false;
 350                 $value = preg_replace_callback( '/\$(\d+|key)/u', array( $this, 'callback' ), $value );
 351                 if ( $this->error ) {
 352                         return false;
 353                 }
 354                 return $value;
 355         }
 356
 357         /**
 358          * @param $m array
 359          * @return string
 360          */
 361         protected function callback( $m ) {
 362                 if ( $m[1] == "key" ) {
 363                         if ( is_null( $this->key ) ) {
 364                                 $this->error = true;
 365                                 return '';
 366                         }
 367                         return $this->key;
 368                 } else {
 369                         $d = $m[1];
 370                         if ( !isset( $this->params["par$d"] ) ) {
 371                                 $this->error = true;
 372                                 return '';
 373                         }
 374                         return rawurldecode( $this->params["par$d"] );
 375                 }
 376         }
 377
 378 }