Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | |
92.59% |
125 / 135 |
|
72.73% |
8 / 11 |
CRAP | |
0.00% |
0 / 1 |
PathRouter | |
93.28% |
125 / 134 |
|
72.73% |
8 / 11 |
60.05 | |
0.00% |
0 / 1 |
doAdd | |
93.33% |
28 / 30 |
|
0.00% |
0 / 1 |
16.08 | |||
add | |
100.00% |
4 / 4 |
|
100.00% |
1 / 1 |
3 | |||
validateRoute | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
3 | |||
addStrict | |
100.00% |
2 / 2 |
|
100.00% |
1 / 1 |
1 | |||
sortByWeight | |
100.00% |
4 / 4 |
|
100.00% |
1 / 1 |
2 | |||
makeWeight | |
100.00% |
12 / 12 |
|
100.00% |
1 / 1 |
6 | |||
parse | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
2 | |||
internalParse | |
100.00% |
6 / 6 |
|
100.00% |
1 / 1 |
3 | |||
extractTitle | |
100.00% |
40 / 40 |
|
100.00% |
1 / 1 |
15 | |||
expandParamValue | |
88.24% |
15 / 17 |
|
0.00% |
0 / 1 |
5.04 | |||
getActionPaths | |
0.00% |
0 / 5 |
|
0.00% |
0 / 1 |
12 |
1 | <?php |
2 | /** |
3 | * Parser to extract query parameters out of REQUEST_URI paths. |
4 | * |
5 | * This program is free software; you can redistribute it and/or modify |
6 | * it under the terms of the GNU General Public License as published by |
7 | * the Free Software Foundation; either version 2 of the License, or |
8 | * (at your option) any later version. |
9 | * |
10 | * This program is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
13 | * GNU General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU General Public License along |
16 | * with this program; if not, write to the Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 | * http://www.gnu.org/copyleft/gpl.html |
19 | * |
20 | * @file |
21 | */ |
22 | |
23 | namespace MediaWiki\Request; |
24 | |
25 | use FatalError; |
26 | use stdClass; |
27 | |
28 | /** |
29 | * MediaWiki\Request\PathRouter class. |
30 | * This class can take patterns such as /wiki/$1 and use them to |
31 | * parse query parameters out of REQUEST_URI paths. |
32 | * |
33 | * $router->add( "/wiki/$1" ); |
34 | * - Matches /wiki/Foo style urls and extracts the title |
35 | * $router->add( [ 'edit' => "/edit/$key" ], [ 'action' => '$key' ] ); |
36 | * - Matches /edit/Foo style urls and sets action=edit |
37 | * $router->add( '/$2/$1', |
38 | * [ 'variant' => '$2' ], |
39 | * [ '$2' => [ 'zh-hant', 'zh-hans' ] ] |
40 | * ); |
41 | * - Matches /zh-hant/Foo or /zh-hans/Foo |
42 | * $router->addStrict( "/foo/Bar", [ 'title' => 'Baz' ] ); |
43 | * - Matches /foo/Bar explicitly and uses "Baz" as the title |
44 | * $router->add( '/help/$1', [ 'title' => 'Help:$1' ] ); |
45 | * - Matches /help/Foo with "Help:Foo" as the title |
46 | * $router->add( '/$1', [ 'foo' => [ 'value' => 'bar$2' ] ] ); |
47 | * - Matches /Foo and sets 'foo' to 'bar$2' without $2 being replaced |
48 | * $router->add( '/$1', [ 'data:foo' => 'bar' ], [ 'callback' => 'functionname' ] ); |
49 | * - Matches /Foo, adds the key 'foo' with the value 'bar' to the data array |
50 | * and calls functionname( &$matches, $data ); |
51 | * |
52 | * Path patterns: |
53 | * - Paths may contain $# patterns such as $1, $2, etc... |
54 | * - $1 will match 0 or more while the rest will match 1 or more |
55 | * - Unless you use addStrict "/wiki" and "/wiki/" will be expanded to "/wiki/$1" |
56 | * |
57 | * Params: |
58 | * - In a pattern $1, $2, etc... will be replaced with the relevant contents |
59 | * - If you used a keyed array as a path pattern, $key will be replaced with |
60 | * the relevant contents |
61 | * - The default behavior is equivalent to `[ 'title' => '$1' ]`, |
62 | * if you don't want the title parameter you can explicitly use `[ 'title' => false ]` |
63 | * - You can specify a value that won't have replacements in it |
64 | * using `'foo' => [ 'value' => 'bar' ];` |
65 | * |
66 | * Options: |
67 | * - The option keys $1, $2, etc... can be specified to restrict the possible values |
68 | * of that variable. A string can be used for a single value, or an array for multiple. |
69 | * - When the option key 'strict' is set (Using addStrict is simpler than doing this directly) |
70 | * the path won't have $1 implicitly added to it. |
71 | * - The option key 'callback' can specify a callback that will be run when a path is matched. |
72 | * The callback will have the arguments ( &$matches, $data ) and the matches array can |
73 | * be modified. |
74 | * |
75 | * @since 1.19 |
76 | * @author Daniel Friesen |
77 | */ |
78 | class PathRouter { |
79 | |
80 | /** |
81 | * @var stdClass[] |
82 | */ |
83 | private $patterns = []; |
84 | |
85 | /** |
86 | * Protected helper to do the actual bulk work of adding a single pattern. |
87 | * This is in a separate method so that add() can handle the difference between |
88 | * a single string $path and an array $path that contains multiple path |
89 | * patterns each with an associated $key to pass on. |
90 | * @param string $path |
91 | * @param array $params |
92 | * @param array $options |
93 | * @param null|string $key |
94 | */ |
95 | protected function doAdd( $path, $params, $options, $key = null ) { |
96 | // Make sure all paths start with a / |
97 | if ( $path[0] !== '/' ) { |
98 | $path = '/' . $path; |
99 | } |
100 | |
101 | if ( !isset( $options['strict'] ) || !$options['strict'] ) { |
102 | // Unless this is a strict path make sure that the path has a $1 |
103 | if ( strpos( $path, '$1' ) === false ) { |
104 | if ( $path[-1] !== '/' ) { |
105 | $path .= '/'; |
106 | } |
107 | $path .= '$1'; |
108 | } |
109 | } |
110 | |
111 | // If 'title' is not specified and our path pattern contains a $1 |
112 | // Add a default 'title' => '$1' rule to the parameters. |
113 | if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) { |
114 | $params['title'] = '$1'; |
115 | } |
116 | // If the user explicitly marked 'title' as false then omit it from the matches |
117 | if ( isset( $params['title'] ) && $params['title'] === false ) { |
118 | unset( $params['title'] ); |
119 | } |
120 | |
121 | // Loop over our parameters and convert basic key => string |
122 | // patterns into fully descriptive array form |
123 | foreach ( $params as $paramName => $paramData ) { |
124 | if ( is_string( $paramData ) ) { |
125 | if ( preg_match( '/\$(\d+|key)/u', $paramData ) ) { |
126 | $paramArrKey = 'pattern'; |
127 | } else { |
128 | // If there's no replacement use a value instead |
129 | // of a pattern for a little more efficiency |
130 | $paramArrKey = 'value'; |
131 | } |
132 | $params[$paramName] = [ |
133 | $paramArrKey => $paramData |
134 | ]; |
135 | } |
136 | } |
137 | |
138 | // Loop over our options and convert any single value $# restrictions |
139 | // into an array so we only have to do in_array tests. |
140 | foreach ( $options as $optionName => $optionData ) { |
141 | if ( preg_match( '/^\$\d+$/u', $optionName ) && !is_array( $optionData ) ) { |
142 | $options[$optionName] = [ $optionData ]; |
143 | } |
144 | } |
145 | |
146 | $pattern = (object)[ |
147 | 'path' => $path, |
148 | 'params' => $params, |
149 | 'options' => $options, |
150 | 'key' => $key, |
151 | ]; |
152 | $pattern->weight = self::makeWeight( $pattern ); |
153 | $this->patterns[] = $pattern; |
154 | } |
155 | |
156 | /** |
157 | * Add a new path pattern to the path router |
158 | * |
159 | * @param string|array $path The path pattern to add |
160 | * @param array $params The params for this path pattern |
161 | * @param array $options The options for this path pattern |
162 | */ |
163 | public function add( $path, $params = [], $options = [] ) { |
164 | if ( is_array( $path ) ) { |
165 | foreach ( $path as $key => $onePath ) { |
166 | $this->doAdd( $onePath, $params, $options, $key ); |
167 | } |
168 | } else { |
169 | $this->doAdd( $path, $params, $options ); |
170 | } |
171 | } |
172 | |
173 | /** |
174 | * @param string $path To be given to add() |
175 | * @param string $varName Full name of configuration variable for use |
176 | * in error message and url to mediawiki.org Manual (e.g. "wgExample"). |
177 | * @throws FatalError If path is invalid |
178 | * @internal For use by WebRequest::getPathInfo |
179 | */ |
180 | public function validateRoute( $path, $varName ) { |
181 | if ( $path && !preg_match( '/^(https?:\/\/|\/)/', $path ) ) { |
182 | // T48998: Bail out early if path is non-absolute |
183 | throw new FatalError( |
184 | "If you use a relative URL for \$$varName, it must start " . |
185 | 'with a slash (<code>/</code>).<br><br>See ' . |
186 | "<a href=\"https://www.mediawiki.org/wiki/Manual:\$$varName\">" . |
187 | "https://www.mediawiki.org/wiki/Manual:\$$varName</a>." |
188 | ); |
189 | } |
190 | } |
191 | |
192 | /** |
193 | * Add a new path pattern to the path router with the strict option on |
194 | * @param string|array $path |
195 | * @param array $params |
196 | * @param array $options |
197 | * @see self::add |
198 | */ |
199 | public function addStrict( $path, $params = [], $options = [] ) { |
200 | $options['strict'] = true; |
201 | $this->add( $path, $params, $options ); |
202 | } |
203 | |
204 | /** |
205 | * Protected helper to re-sort our patterns so that the most specific |
206 | * (most heavily weighted) patterns are at the start of the array. |
207 | */ |
208 | protected function sortByWeight() { |
209 | $weights = []; |
210 | foreach ( $this->patterns as $key => $pattern ) { |
211 | $weights[$key] = $pattern->weight; |
212 | } |
213 | array_multisort( $weights, SORT_DESC, SORT_NUMERIC, $this->patterns ); |
214 | } |
215 | |
216 | /** |
217 | * @param stdClass $pattern |
218 | * @return float|int |
219 | */ |
220 | protected static function makeWeight( $pattern ) { |
221 | # Start with a weight of 0 |
222 | $weight = 0; |
223 | |
224 | // Explode the path to work with |
225 | $path = explode( '/', $pattern->path ); |
226 | |
227 | # For each level of the path |
228 | foreach ( $path as $piece ) { |
229 | if ( preg_match( '/^\$(\d+|key)$/u', $piece ) ) { |
230 | # For a piece that is only a $1 variable add 1 points of weight |
231 | $weight += 1; |
232 | } elseif ( preg_match( '/\$(\d+|key)/u', $piece ) ) { |
233 | # For a piece that simply contains a $1 variable add 2 points of weight |
234 | $weight += 2; |
235 | } else { |
236 | # For a solid piece add a full 3 points of weight |
237 | $weight += 3; |
238 | } |
239 | } |
240 | |
241 | foreach ( $pattern->options as $key => $option ) { |
242 | if ( preg_match( '/^\$\d+$/u', $key ) ) { |
243 | # Add 0.5 for restrictions to values |
244 | # This way given two separate "/$2/$1" patterns the |
245 | # one with a limited set of $2 values will dominate |
246 | # the one that'll match more loosely |
247 | $weight += 0.5; |
248 | } |
249 | } |
250 | |
251 | return $weight; |
252 | } |
253 | |
254 | /** |
255 | * Parse a path and return the query matches for the path |
256 | * |
257 | * @param string $path The path to parse |
258 | * @return array The array of matches for the path |
259 | */ |
260 | public function parse( $path ) { |
261 | // Make sure our patterns are sorted by weight so the most specific |
262 | // matches are tested first |
263 | $this->sortByWeight(); |
264 | |
265 | $matches = $this->internalParse( $path ); |
266 | if ( $matches === null ) { |
267 | // Try with the normalized path (T100782) |
268 | $path = wfRemoveDotSegments( $path ); |
269 | $path = preg_replace( '#/+#', '/', $path ); |
270 | $matches = $this->internalParse( $path ); |
271 | } |
272 | |
273 | // We know the difference between null (no matches) and |
274 | // [] (a match with no data) but our WebRequest caller |
275 | // expects [] even when we have no matches so return |
276 | // a [] when we have null |
277 | return $matches ?? []; |
278 | } |
279 | |
280 | /** |
281 | * Match a path against each defined pattern |
282 | * |
283 | * @param string $path |
284 | * @return array|null |
285 | */ |
286 | protected function internalParse( $path ) { |
287 | $matches = null; |
288 | |
289 | foreach ( $this->patterns as $pattern ) { |
290 | $matches = self::extractTitle( $path, $pattern ); |
291 | if ( $matches !== null ) { |
292 | break; |
293 | } |
294 | } |
295 | return $matches; |
296 | } |
297 | |
298 | /** |
299 | * @param string $path |
300 | * @param stdClass $pattern |
301 | * @return array|null |
302 | */ |
303 | protected static function extractTitle( $path, $pattern ) { |
304 | // Convert the path pattern into a regexp we can match with |
305 | $regexp = preg_quote( $pattern->path, '#' ); |
306 | // .* for the $1 |
307 | $regexp = preg_replace( '#\\\\\$1#u', '(?P<par1>.*)', $regexp ); |
308 | // .+ for the rest of the parameter numbers |
309 | $regexp = preg_replace( '#\\\\\$(\d+)#u', '(?P<par$1>.+?)', $regexp ); |
310 | $regexp = "#^{$regexp}$#"; |
311 | |
312 | $matches = []; |
313 | $data = []; |
314 | |
315 | // Try to match the path we were asked to parse with our regexp |
316 | if ( preg_match( $regexp, $path, $m ) ) { |
317 | // Ensure that any $# restriction we have set in our {$option}s |
318 | // matches properly here. |
319 | foreach ( $pattern->options as $key => $option ) { |
320 | if ( preg_match( '/^\$\d+$/u', $key ) ) { |
321 | $n = intval( substr( $key, 1 ) ); |
322 | $value = rawurldecode( $m["par{$n}"] ); |
323 | if ( !in_array( $value, $option ) ) { |
324 | // If any restriction does not match return null |
325 | // to signify that this rule did not match. |
326 | return null; |
327 | } |
328 | } |
329 | } |
330 | |
331 | // Give our $data array a copy of every $# that was matched |
332 | foreach ( $m as $matchKey => $matchValue ) { |
333 | if ( preg_match( '/^par\d+$/u', $matchKey ) ) { |
334 | $n = intval( substr( $matchKey, 3 ) ); |
335 | $data['$' . $n] = rawurldecode( $matchValue ); |
336 | } |
337 | } |
338 | // If present give our $data array a $key as well |
339 | if ( isset( $pattern->key ) ) { |
340 | $data['$key'] = $pattern->key; |
341 | } |
342 | |
343 | // Go through our parameters for this match and add data to our matches and data arrays |
344 | foreach ( $pattern->params as $paramName => $paramData ) { |
345 | $value = null; |
346 | // Differentiate data: from normal parameters and keep the correct |
347 | // array key around (ie: foo for data:foo) |
348 | if ( preg_match( '/^data:/u', $paramName ) ) { |
349 | $isData = true; |
350 | $key = substr( $paramName, 5 ); |
351 | } else { |
352 | $isData = false; |
353 | $key = $paramName; |
354 | } |
355 | |
356 | if ( isset( $paramData['value'] ) ) { |
357 | // For basic values just set the raw data as the value |
358 | $value = $paramData['value']; |
359 | } elseif ( isset( $paramData['pattern'] ) ) { |
360 | // For patterns we have to make value replacements on the string |
361 | $value = self::expandParamValue( $m, $pattern->key ?? null, |
362 | $paramData['pattern'] ); |
363 | if ( $value === false ) { |
364 | // Pattern required data that wasn't available, abort |
365 | return null; |
366 | } |
367 | } |
368 | |
369 | // Send things that start with data: to $data, the rest to $matches |
370 | if ( $isData ) { |
371 | $data[$key] = $value; |
372 | } else { |
373 | $matches[$key] = $value; |
374 | } |
375 | } |
376 | |
377 | // If this match includes a callback, execute it |
378 | if ( isset( $pattern->options['callback'] ) ) { |
379 | call_user_func_array( $pattern->options['callback'], [ &$matches, $data ] ); |
380 | } |
381 | } else { |
382 | // Our regexp didn't match, return null to signify no match. |
383 | return null; |
384 | } |
385 | // Fall through, everything went ok, return our matches array |
386 | return $matches; |
387 | } |
388 | |
389 | /** |
390 | * Replace $key etc. in param values with the matched strings from the path. |
391 | * |
392 | * @param array $pathMatches The match results from the path |
393 | * @param string|null $key The key of the matching pattern |
394 | * @param string $value The param value to be expanded |
395 | * @return string|false |
396 | */ |
397 | protected static function expandParamValue( $pathMatches, $key, $value ) { |
398 | $error = false; |
399 | |
400 | $replacer = static function ( $m ) use ( $pathMatches, $key, &$error ) { |
401 | if ( $m[1] == "key" ) { |
402 | if ( $key === null ) { |
403 | $error = true; |
404 | |
405 | return ''; |
406 | } |
407 | |
408 | return $key; |
409 | } else { |
410 | $d = $m[1]; |
411 | if ( !isset( $pathMatches["par$d"] ) ) { |
412 | $error = true; |
413 | |
414 | return ''; |
415 | } |
416 | |
417 | return rawurldecode( $pathMatches["par$d"] ); |
418 | } |
419 | }; |
420 | |
421 | $value = preg_replace_callback( '/\$(\d+|key)/u', $replacer, $value ); |
422 | if ( $error ) { |
423 | return false; |
424 | } |
425 | |
426 | return $value; |
427 | } |
428 | |
429 | /** |
430 | * @param array $actionPaths |
431 | * @param string $articlePath |
432 | * @return string[]|false |
433 | * @internal For use by Title and WebRequest only. |
434 | */ |
435 | public static function getActionPaths( array $actionPaths, $articlePath ) { |
436 | if ( !$actionPaths ) { |
437 | return false; |
438 | } |
439 | // Processing of urls for this feature requires that 'view' is set. |
440 | // By default, set it to the pretty article path. |
441 | if ( !isset( $actionPaths['view'] ) ) { |
442 | $actionPaths['view'] = $articlePath; |
443 | } |
444 | return $actionPaths; |
445 | } |
446 | } |
447 | |
448 | /** @deprecated class alias since 1.40 */ |
449 | class_alias( PathRouter::class, 'PathRouter' ); |