4 * This class can take patterns such as /wiki/$1 and use them to
5 * parse query parameters out of REQUEST_URI paths.
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' )
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 );
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"
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' );`
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
50 * @author Daniel Friesen
53 protected function doAdd( $path, $params, $options, $key = null ) {
54 if ( $path[0] !== '/' ) {
58 if ( !isset( $options['strict'] ) ||
!$options['strict'] ) {
59 // Unless this is a strict path make sure that the path has a $1
60 if ( strpos( $path, '$1' ) === false ) {
61 if ( substr( $path, -1 ) !== '/' ) {
68 if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) {
69 $params['title'] = '$1';
71 if ( isset( $params['title'] ) && $params['title'] === false ) {
72 unset( $params['title'] );
75 foreach ( $params as $paramName => $paramData ) {
76 if ( is_string( $paramData ) ) {
77 if ( preg_match( '/\$(\d+|key)/u', $paramData ) ) {
78 $paramArrKey = 'pattern';
80 // If there's no replacement use a value instead
81 // of a pattern for a little more efficiency
82 $paramArrKey = 'value';
84 $params[$paramName] = array(
85 $paramArrKey => $paramData
90 foreach ( $options as $optionName => $optionData ) {
91 if ( preg_match( '/^\$\d+$/u', $optionName ) ) {
92 if ( !is_array( $optionData ) ) {
93 $options[$optionName] = array( $optionData );
98 $pattern = (object)array(
101 'options' => $options,
104 $pattern->weight
= self
::makeWeight( $pattern );
105 $this->patterns
[] = $pattern;
109 * Add a new path pattern to the path router
111 * @param $path The path pattern to add
112 * @param $params The params for this path pattern
113 * @param $options The options for this path pattern
115 public function add( $path, $params = array(), $options = array() ) {
116 if ( is_array( $path ) ) {
117 foreach ( $path as $key => $onePath ) {
118 $this->doAdd( $onePath, $params, $options, $key );
121 $this->doAdd( $path, $params, $options );
126 * Add a new path pattern to the path router with the strict option on
129 public function addStrict( $path, $params = array(), $options = array() ) {
130 $options['strict'] = true;
131 $this->add( $path, $params, $options );
134 protected function sortByWeight() {
136 foreach( $this->patterns
as $key => $pattern ) {
137 $weights[$key] = $pattern->weight
;
139 array_multisort( $weights, SORT_DESC
, SORT_NUMERIC
, $this->patterns
);
142 public static function makeWeight( $pattern ) {
143 # Start with a weight of 0
146 // Explode the path to work with
147 $path = explode( '/', $pattern->path
);
149 # For each level of the path
150 foreach( $path as $piece ) {
151 if ( preg_match( '/^\$(\d+|key)$/u', $piece ) ) {
152 # For a piece that is only a $1 variable add 1 points of weight
154 } elseif ( preg_match( '/\$(\d+|key)/u', $piece ) ) {
155 # For a piece that simply contains a $1 variable add 2 points of weight
158 # For a solid piece add a full 3 points of weight
163 foreach ( $pattern->options
as $key => $option ) {
164 if ( preg_match( '/^\$\d+$/u', $key ) ) {
165 # Add 0.5 for restrictions to values
166 # This way given two separate "/$2/$1" patterns the
167 # one with a limited set of $2 values will dominate
168 # the one that'll match more loosely
177 * Parse a path and return the query matches for the path
179 * @param $path The path to parse
180 * @return Array The array of matches for the path
182 public function parse( $path ) {
183 $this->sortByWeight();
187 foreach ( $this->patterns
as $pattern ) {
188 $matches = self
::extractTitle( $path, $pattern );
189 if ( !is_null( $matches ) ) {
194 return is_null( $matches ) ?
array() : $matches;
197 protected static function extractTitle( $path, $pattern ) {
198 $regexp = preg_quote( $pattern->path
, '#' );
199 $regexp = preg_replace( '#\\\\\$1#u', '(?P<par1>.*)', $regexp );
200 $regexp = preg_replace( '#\\\\\$(\d+)#u', '(?P<par$1>.+?)', $regexp );
201 $regexp = "#^{$regexp}$#";
206 if ( preg_match( $regexp, $path, $m ) ) {
207 foreach ( $pattern->options
as $key => $option ) {
208 if ( preg_match( '/^\$\d+$/u', $key ) ) {
209 $n = intval( substr( $key, 1 ) );
210 $value = rawurldecode( $m["par{$n}"] );
211 if ( !in_array( $value, $option ) ) {
217 foreach ( $m as $matchKey => $matchValue ) {
218 if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
219 $n = intval( substr( $matchKey, 3 ) );
220 $data['$'.$n] = rawurldecode( $matchValue );
223 if ( isset( $pattern->key
) ) {
224 $data['$key'] = $pattern->key
;
227 foreach ( $pattern->params
as $paramName => $paramData ) {
229 if ( preg_match( '/^data:/u', $paramName ) ) {
231 $key = substr( $paramName, 5 );
237 if ( isset( $paramData['value'] ) ) {
238 $value = $paramData['value'];
239 } elseif ( isset( $paramData['pattern'] ) ) {
240 $value = $paramData['pattern'];
241 foreach ( $m as $matchKey => $matchValue ) {
242 if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
243 $n = intval( substr( $matchKey, 3 ) );
244 $value = str_replace( '$' . $n, rawurldecode( $matchValue ), $value );
247 if ( isset( $pattern->key
) ) {
248 $value = str_replace( '$key', $pattern->key
, $value );
250 if ( preg_match( '/\$(\d+|key)/u', $value ) ) {
251 // Still contains $# or $key patterns after replacement
252 // Seams like we don't have all the data, abort
258 $data[$key] = $value;
260 $matches[$key] = $value;
264 if ( isset( $pattern->options
['callback'] ) ) {
265 call_user_func_array( $pattern->options
['callback'], array( &$matches, $data ) );