3 * Parser to extract query parameters out of REQUEST_URI paths.
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.
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.
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
25 * This class can take patterns such as /wiki/$1 and use them to
26 * parse query parameters out of REQUEST_URI paths.
28 * $router->add( "/wiki/$1" );
29 * - Matches /wiki/Foo style urls and extracts the title
30 * $router->add( [ 'edit' => "/edit/$key" ], [ 'action' => '$key' ] );
31 * - Matches /edit/Foo style urls and sets action=edit
32 * $router->add( '/$2/$1',
33 * [ 'variant' => '$2' ],
34 * [ '$2' => [ 'zh-hant', 'zh-hans' ] ]
36 * - Matches /zh-hant/Foo or /zh-hans/Foo
37 * $router->addStrict( "/foo/Bar", [ 'title' => 'Baz' ] );
38 * - Matches /foo/Bar explicitly and uses "Baz" as the title
39 * $router->add( '/help/$1', [ 'title' => 'Help:$1' ] );
40 * - Matches /help/Foo with "Help:Foo" as the title
41 * $router->add( '/$1', [ 'foo' => [ 'value' => 'bar$2' ] ] );
42 * - Matches /Foo and sets 'foo' to 'bar$2' without $2 being replaced
43 * $router->add( '/$1', [ 'data:foo' => 'bar' ], [ 'callback' => 'functionname' ] );
44 * - Matches /Foo, adds the key 'foo' with the value 'bar' to the data array
45 * and calls functionname( &$matches, $data );
48 * - Paths may contain $# patterns such as $1, $2, etc...
49 * - $1 will match 0 or more while the rest will match 1 or more
50 * - Unless you use addStrict "/wiki" and "/wiki/" will be expanded to "/wiki/$1"
53 * - In a pattern $1, $2, etc... will be replaced with the relevant contents
54 * - If you used a keyed array as a path pattern, $key will be replaced with
55 * the relevant contents
56 * - The default behavior is equivalent to `[ 'title' => '$1' ]`,
57 * if you don't want the title parameter you can explicitly use `[ 'title' => false ]`
58 * - You can specify a value that won't have replacements in it
59 * using `'foo' => [ 'value' => 'bar' ];`
62 * - The option keys $1, $2, etc... can be specified to restrict the possible values
63 * of that variable. A string can be used for a single value, or an array for multiple.
64 * - When the option key 'strict' is set (Using addStrict is simpler than doing this directly)
65 * the path won't have $1 implicitly added to it.
66 * - The option key 'callback' can specify a callback that will be run when a path is matched.
67 * The callback will have the arguments ( &$matches, $data ) and the matches array can
71 * @author Daniel Friesen
78 private $patterns = [];
81 * Protected helper to do the actual bulk work of adding a single pattern.
82 * This is in a separate method so that add() can handle the difference between
83 * a single string $path and an array $path that contains multiple path
84 * patterns each with an associated $key to pass on.
86 * @param array $params
87 * @param array $options
88 * @param null|string $key
90 protected function doAdd( $path, $params, $options, $key = null ) {
91 // Make sure all paths start with a /
92 if ( $path[0] !== '/' ) {
96 if ( !isset( $options['strict'] ) ||
!$options['strict'] ) {
97 // Unless this is a strict path make sure that the path has a $1
98 if ( strpos( $path, '$1' ) === false ) {
99 if ( substr( $path, -1 ) !== '/' ) {
106 // If 'title' is not specified and our path pattern contains a $1
107 // Add a default 'title' => '$1' rule to the parameters.
108 if ( !isset( $params['title'] ) && strpos( $path, '$1' ) !== false ) {
109 $params['title'] = '$1';
111 // If the user explicitly marked 'title' as false then omit it from the matches
112 if ( isset( $params['title'] ) && $params['title'] === false ) {
113 unset( $params['title'] );
116 // Loop over our parameters and convert basic key => string
117 // patterns into fully descriptive array form
118 foreach ( $params as $paramName => $paramData ) {
119 if ( is_string( $paramData ) ) {
120 if ( preg_match( '/\$(\d+|key)/u', $paramData ) ) {
121 $paramArrKey = 'pattern';
123 // If there's no replacement use a value instead
124 // of a pattern for a little more efficiency
125 $paramArrKey = 'value';
127 $params[$paramName] = [
128 $paramArrKey => $paramData
133 // Loop over our options and convert any single value $# restrictions
134 // into an array so we only have to do in_array tests.
135 foreach ( $options as $optionName => $optionData ) {
136 if ( preg_match( '/^\$\d+$/u', $optionName ) && !is_array( $optionData ) ) {
137 $options[$optionName] = [ $optionData ];
144 'options' => $options,
147 $pattern->weight
= self
::makeWeight( $pattern );
148 $this->patterns
[] = $pattern;
152 * Add a new path pattern to the path router
154 * @param string|array $path The path pattern to add
155 * @param array $params The params for this path pattern
156 * @param array $options The options for this path pattern
158 public function add( $path, $params = [], $options = [] ) {
159 if ( is_array( $path ) ) {
160 foreach ( $path as $key => $onePath ) {
161 $this->doAdd( $onePath, $params, $options, $key );
164 $this->doAdd( $path, $params, $options );
169 * Add a new path pattern to the path router with the strict option on
171 * @param string|array $path
172 * @param array $params
173 * @param array $options
175 public function addStrict( $path, $params = [], $options = [] ) {
176 $options['strict'] = true;
177 $this->add( $path, $params, $options );
181 * Protected helper to re-sort our patterns so that the most specific
182 * (most heavily weighted) patterns are at the start of the array.
184 protected function sortByWeight() {
186 foreach ( $this->patterns
as $key => $pattern ) {
187 $weights[$key] = $pattern->weight
;
189 array_multisort( $weights, SORT_DESC
, SORT_NUMERIC
, $this->patterns
);
193 * @param object $pattern
196 protected static function makeWeight( $pattern ) {
197 # Start with a weight of 0
200 // Explode the path to work with
201 $path = explode( '/', $pattern->path
);
203 # For each level of the path
204 foreach ( $path as $piece ) {
205 if ( preg_match( '/^\$(\d+|key)$/u', $piece ) ) {
206 # For a piece that is only a $1 variable add 1 points of weight
208 } elseif ( preg_match( '/\$(\d+|key)/u', $piece ) ) {
209 # For a piece that simply contains a $1 variable add 2 points of weight
212 # For a solid piece add a full 3 points of weight
217 foreach ( $pattern->options
as $key => $option ) {
218 if ( preg_match( '/^\$\d+$/u', $key ) ) {
219 # Add 0.5 for restrictions to values
220 # This way given two separate "/$2/$1" patterns the
221 # one with a limited set of $2 values will dominate
222 # the one that'll match more loosely
231 * Parse a path and return the query matches for the path
233 * @param string $path The path to parse
234 * @return array The array of matches for the path
236 public function parse( $path ) {
237 // Make sure our patterns are sorted by weight so the most specific
238 // matches are tested first
239 $this->sortByWeight();
241 $matches = $this->internalParse( $path );
242 if ( is_null( $matches ) ) {
243 // Try with the normalized path (T100782)
244 $path = wfRemoveDotSegments( $path );
245 $path = preg_replace( '#/+#', '/', $path );
246 $matches = $this->internalParse( $path );
249 // We know the difference between null (no matches) and
250 // [] (a match with no data) but our WebRequest caller
251 // expects [] even when we have no matches so return
252 // a [] when we have null
253 return $matches ??
[];
257 * Match a path against each defined pattern
259 * @param string $path
262 protected function internalParse( $path ) {
265 foreach ( $this->patterns
as $pattern ) {
266 $matches = self
::extractTitle( $path, $pattern );
267 if ( !is_null( $matches ) ) {
275 * @param string $path
276 * @param object $pattern
279 protected static function extractTitle( $path, $pattern ) {
280 // Convert the path pattern into a regexp we can match with
281 $regexp = preg_quote( $pattern->path
, '#' );
283 $regexp = preg_replace( '#\\\\\$1#u', '(?P<par1>.*)', $regexp );
284 // .+ for the rest of the parameter numbers
285 $regexp = preg_replace( '#\\\\\$(\d+)#u', '(?P<par$1>.+?)', $regexp );
286 $regexp = "#^{$regexp}$#";
291 // Try to match the path we were asked to parse with our regexp
292 if ( preg_match( $regexp, $path, $m ) ) {
293 // Ensure that any $# restriction we have set in our {$option}s
294 // matches properly here.
295 foreach ( $pattern->options
as $key => $option ) {
296 if ( preg_match( '/^\$\d+$/u', $key ) ) {
297 $n = intval( substr( $key, 1 ) );
298 $value = rawurldecode( $m["par{$n}"] );
299 if ( !in_array( $value, $option ) ) {
300 // If any restriction does not match return null
301 // to signify that this rule did not match.
307 // Give our $data array a copy of every $# that was matched
308 foreach ( $m as $matchKey => $matchValue ) {
309 if ( preg_match( '/^par\d+$/u', $matchKey ) ) {
310 $n = intval( substr( $matchKey, 3 ) );
311 $data['$' . $n] = rawurldecode( $matchValue );
314 // If present give our $data array a $key as well
315 if ( isset( $pattern->key
) ) {
316 $data['$key'] = $pattern->key
;
319 // Go through our parameters for this match and add data to our matches and data arrays
320 foreach ( $pattern->params
as $paramName => $paramData ) {
322 // Differentiate data: from normal parameters and keep the correct
323 // array key around (ie: foo for data:foo)
324 if ( preg_match( '/^data:/u', $paramName ) ) {
326 $key = substr( $paramName, 5 );
332 if ( isset( $paramData['value'] ) ) {
333 // For basic values just set the raw data as the value
334 $value = $paramData['value'];
335 } elseif ( isset( $paramData['pattern'] ) ) {
336 // For patterns we have to make value replacements on the string
337 $value = self
::expandParamValue( $m, $pattern->key ??
null,
338 $paramData['pattern'] );
339 if ( $value === false ) {
340 // Pattern required data that wasn't available, abort
345 // Send things that start with data: to $data, the rest to $matches
347 $data[$key] = $value;
349 $matches[$key] = $value;
353 // If this match includes a callback, execute it
354 if ( isset( $pattern->options
['callback'] ) ) {
355 call_user_func_array( $pattern->options
['callback'], [ &$matches, $data ] );
358 // Our regexp didn't match, return null to signify no match.
361 // Fall through, everything went ok, return our matches array
366 * Replace $key etc. in param values with the matched strings from the path.
368 * @param array $pathMatches The match results from the path
369 * @param string|null $key The key of the matching pattern
370 * @param string $value The param value to be expanded
371 * @return string|false
373 protected static function expandParamValue( $pathMatches, $key, $value ) {
376 $replacer = function ( $m ) use ( $pathMatches, $key, &$error ) {
377 if ( $m[1] == "key" ) {
378 if ( is_null( $key ) ) {
387 if ( !isset( $pathMatches["par$d"] ) ) {
393 return rawurldecode( $pathMatches["par$d"] );
397 $value = preg_replace_callback( '/\$(\d+|key)/u', $replacer, $value );
406 * @internal For use by Title and WebRequest only.
407 * @param array $actionPaths
408 * @param string $articlePath
409 * @return string[]|false
411 public static function getActionPaths( array $actionPaths, $articlePath ) {
412 if ( !$actionPaths ) {
415 // Processing of urls for this feature requires that 'view' is set.
416 // By default, set it to the pretty article path.
417 if ( !isset( $actionPaths['view'] ) ) {
418 $actionPaths['view'] = $articlePath;