1 | <?php |
||
2 | |||
3 | /** |
||
4 | * League.Uri (https://uri.thephpleague.com) |
||
5 | * |
||
6 | * (c) Ignace Nyamagana Butera <[email protected]> |
||
7 | * |
||
8 | * For the full copyright and license information, please view the LICENSE |
||
9 | * file that was distributed with this source code. |
||
10 | */ |
||
11 | |||
12 | declare(strict_types=1); |
||
13 | |||
14 | namespace League\Uri; |
||
15 | |||
16 | use League\Uri\Contracts\UriException; |
||
17 | use League\Uri\Contracts\UriInterface; |
||
18 | use League\Uri\Exceptions\SyntaxError; |
||
19 | use League\Uri\Exceptions\TemplateCanNotBeExpanded; |
||
20 | use function array_filter; |
||
21 | use function array_keys; |
||
22 | use function explode; |
||
23 | use function gettype; |
||
24 | use function implode; |
||
25 | use function in_array; |
||
26 | use function is_array; |
||
27 | use function is_bool; |
||
28 | use function is_scalar; |
||
29 | use function is_string; |
||
30 | use function method_exists; |
||
31 | use function preg_match; |
||
32 | use function preg_match_all; |
||
33 | use function preg_replace; |
||
34 | use function preg_replace_callback; |
||
35 | use function rawurlencode; |
||
36 | use function sprintf; |
||
37 | use function strpos; |
||
38 | use function substr; |
||
39 | use const ARRAY_FILTER_USE_KEY; |
||
40 | use const PREG_SET_ORDER; |
||
41 | |||
42 | /** |
||
43 | * Expands URI templates. |
||
44 | * |
||
45 | * @link http://tools.ietf.org/html/rfc6570 |
||
46 | * |
||
47 | * Based on GuzzleHttp\UriTemplate class which is removed from Guzzle7. |
||
48 | * @see https://github.com/guzzle/guzzle/blob/6.5/src/UriTemplate.php |
||
49 | */ |
||
50 | final class UriTemplate |
||
51 | { |
||
52 | private const REGEXP_EXPRESSION = '/\{ |
||
53 | (?<expression> |
||
54 | (?<operator>[\.\/;\?&\=,\!@\|\+#])? |
||
55 | (?<variables>[^\}]*) |
||
56 | ) |
||
57 | \}/x'; |
||
58 | |||
59 | private const REGEXP_VARSPEC = '/^ |
||
60 | (?<name>(?:[A-z0-9_\.]|%[0-9a-fA-F]{2})+) |
||
61 | (?<modifier>\:(?<position>\d+)|\*)? |
||
62 | $/x'; |
||
63 | |||
64 | private const RESERVED_OPERATOR = '=,!@|'; |
||
65 | |||
66 | private const OPERATOR_HASH_LOOKUP = [ |
||
67 | '' => ['prefix' => '', 'joiner' => ',', 'query' => false], |
||
68 | '+' => ['prefix' => '', 'joiner' => ',', 'query' => false], |
||
69 | '#' => ['prefix' => '#', 'joiner' => ',', 'query' => false], |
||
70 | '.' => ['prefix' => '.', 'joiner' => '.', 'query' => false], |
||
71 | '/' => ['prefix' => '/', 'joiner' => '/', 'query' => false], |
||
72 | ';' => ['prefix' => ';', 'joiner' => ';', 'query' => true], |
||
73 | '?' => ['prefix' => '?', 'joiner' => '&', 'query' => true], |
||
74 | '&' => ['prefix' => '&', 'joiner' => '&', 'query' => true], |
||
75 | ]; |
||
76 | |||
77 | /** |
||
78 | * @var string |
||
79 | */ |
||
80 | private $template; |
||
81 | |||
82 | /** |
||
83 | * @var array<string,string|array> |
||
84 | */ |
||
85 | private $defaultVariables; |
||
86 | |||
87 | /** |
||
88 | * @var string[] |
||
89 | */ |
||
90 | private $variableNames; |
||
91 | |||
92 | /** |
||
93 | * @var array<string, array{ |
||
0 ignored issues
–
show
Documentation
Bug
introduced
by
Loading history...
|
|||
94 | * pattern:string, |
||
95 | * operator:string, |
||
96 | * variables:array<array{ |
||
97 | * name: string, |
||
98 | * modifier: string, |
||
99 | * position: string |
||
100 | * }>, |
||
101 | * joiner:string, |
||
102 | * prefix:string, |
||
103 | * query:bool |
||
104 | * }> |
||
105 | */ |
||
106 | private $expressions; |
||
107 | |||
108 | /** |
||
109 | * @var array{noExpression:UriInterface|null, noVariables:UriInterface|null} |
||
110 | */ |
||
111 | private $cache; |
||
112 | |||
113 | /** |
||
114 | * @var array<string,string|array> |
||
115 | */ |
||
116 | private $variables; |
||
117 | |||
118 | /** |
||
119 | * @param object|string $template a string or an object with the __toString method |
||
120 | * |
||
121 | * @throws \TypeError if the template is not a string or an object with the __toString method |
||
122 | * @throws TemplateCanNotBeExpanded if the template syntax is invalid |
||
123 | */ |
||
124 | 6 | public function __construct($template, array $defaultVariables = []) |
|
125 | { |
||
126 | 6 | $this->template = $this->filterTemplate($template); |
|
127 | |||
128 | 4 | $this->parseExpressions(); |
|
129 | |||
130 | 4 | $this->defaultVariables = $this->filterVariables($defaultVariables); |
|
131 | 4 | } |
|
132 | |||
133 | /** |
||
134 | * {@inheritDoc} |
||
135 | */ |
||
136 | 2 | public static function __set_state(array $properties): self |
|
137 | { |
||
138 | 2 | return new self($properties['template'], $properties['defaultVariables']); |
|
139 | } |
||
140 | |||
141 | /** |
||
142 | * @param object|string $template a string or an object with the __toString method |
||
143 | * |
||
144 | * @throws \TypeError if the template is not a string or an object with the __toString method |
||
145 | */ |
||
146 | 4 | private function filterTemplate($template): string |
|
147 | { |
||
148 | 4 | if (!is_string($template) && !method_exists($template, '__toString')) { |
|
149 | 2 | throw new \TypeError(sprintf('The template must be a string or a stringable object %s given.', gettype($template))); |
|
150 | } |
||
151 | |||
152 | 2 | return (string) $template; |
|
153 | } |
||
154 | |||
155 | /** |
||
156 | * Parses the template expressions. |
||
157 | * |
||
158 | * @throws SyntaxError if the template syntax is invalid |
||
159 | */ |
||
160 | 70 | private function parseExpressions(): void |
|
161 | { |
||
162 | 70 | $this->cache = ['noExpression' => null, 'noVariables' => null]; |
|
163 | /** @var string $remainder */ |
||
164 | 70 | $remainder = preg_replace(self::REGEXP_EXPRESSION, '', $this->template); |
|
165 | 70 | if (false !== strpos($remainder, '{') || false !== strpos($remainder, '}')) { |
|
166 | 6 | throw new SyntaxError('The submitted template "'.$this->template.'" contains invalid expressions.'); |
|
167 | } |
||
168 | |||
169 | 64 | preg_match_all(self::REGEXP_EXPRESSION, $this->template, $expressions, PREG_SET_ORDER); |
|
170 | 64 | $this->expressions = []; |
|
171 | 64 | $foundVariables = []; |
|
172 | 64 | foreach ($expressions as $expression) { |
|
173 | 62 | if (isset($this->expressions[$expression['expression']])) { |
|
174 | 2 | continue; |
|
175 | } |
||
176 | |||
177 | /** @var array{expression:string, operator:string, variables:string, pattern:string} $expression */ |
||
178 | 62 | $expression = $expression + ['operator' => '', 'pattern' => '{'.$expression['expression'].'}']; |
|
179 | 62 | [$parsedVariables, $foundVariables] = $this->parseVariableSpecification($expression, $foundVariables); |
|
180 | 12 | $this->expressions[$expression['expression']] = ['variables' => $parsedVariables] |
|
181 | 12 | + $expression |
|
182 | 12 | + self::OPERATOR_HASH_LOOKUP[$expression['operator']]; |
|
183 | } |
||
184 | |||
185 | 10 | $this->variableNames = array_keys($foundVariables); |
|
186 | 10 | } |
|
187 | |||
188 | /** |
||
189 | * Parses a variable specification in conformance to RFC6570. |
||
190 | * |
||
191 | * @param array{expression:string, operator:string, variables:string, pattern:string} $expression |
||
192 | * @param array<string,int> $foundVariables |
||
193 | * |
||
194 | * @throws SyntaxError if the expression does not conform to RFC6570 |
||
195 | * |
||
196 | * @return array{0:array<array{name:string, modifier:string, position:string}>, 1:array<string,int>} |
||
197 | */ |
||
198 | 60 | private function parseVariableSpecification(array $expression, array $foundVariables): array |
|
199 | { |
||
200 | 60 | $parsedVariableSpecification = []; |
|
201 | 60 | if ('' !== $expression['operator'] && false !== strpos(self::RESERVED_OPERATOR, $expression['operator'])) { |
|
202 | 6 | throw new SyntaxError('The operator used in the expression "'.$expression['pattern'].'" is reserved.'); |
|
203 | } |
||
204 | |||
205 | 54 | foreach (explode(',', $expression['variables']) as $varSpec) { |
|
206 | 54 | if ('' === $varSpec) { |
|
207 | 2 | throw new SyntaxError('No variable specification was included in the expression "'.$expression['pattern'].'".'); |
|
208 | } |
||
209 | |||
210 | 52 | if (1 !== preg_match(self::REGEXP_VARSPEC, $varSpec, $parsed)) { |
|
211 | 46 | throw new SyntaxError('The variable specification "'.$varSpec.'" included in the expression "'.$expression['pattern'].'" is invalid.'); |
|
212 | } |
||
213 | |||
214 | 14 | $parsed += ['modifier' => '', 'position' => '']; |
|
215 | 14 | if ('' !== $parsed['position']) { |
|
216 | 2 | $parsed['position'] = (int) $parsed['position']; |
|
217 | 2 | $parsed['modifier'] = ':'; |
|
218 | } |
||
219 | |||
220 | 14 | $foundVariables[$parsed['name']] = 1; |
|
221 | 14 | $parsedVariableSpecification[] = $parsed; |
|
222 | } |
||
223 | |||
224 | /** @var array{0:array<array{name:string, modifier:string, position:string}>, 1:array<string,int>} $result */ |
||
225 | 10 | $result = [$parsedVariableSpecification, $foundVariables]; |
|
226 | |||
227 | 10 | return $result; |
|
228 | } |
||
229 | |||
230 | /** |
||
231 | * Filter out the value whose key is not a valid variable name for the given template. |
||
232 | */ |
||
233 | 8 | private function filterVariables(array $variables): array |
|
234 | { |
||
235 | $filter = function ($key): bool { |
||
236 | 8 | return in_array($key, $this->variableNames, true); |
|
237 | 8 | }; |
|
238 | |||
239 | 8 | return array_filter($variables, $filter, ARRAY_FILTER_USE_KEY); |
|
240 | } |
||
241 | |||
242 | /** |
||
243 | * The template string. |
||
244 | */ |
||
245 | 2 | public function getTemplate(): string |
|
246 | { |
||
247 | 2 | return $this->template; |
|
248 | } |
||
249 | |||
250 | /** |
||
251 | * Returns the names of the variables in the template, in order. |
||
252 | * |
||
253 | * @return string[] |
||
254 | */ |
||
255 | 8 | public function getVariableNames(): array |
|
256 | { |
||
257 | 8 | return $this->variableNames; |
|
258 | } |
||
259 | |||
260 | /** |
||
261 | * Returns a new instance with the updated template. |
||
262 | * |
||
263 | * This method MUST retain the state of the current instance, and return |
||
264 | * an instance that contains the modified template value. |
||
265 | * |
||
266 | * @param object|string $template a string or an object with the __toString method |
||
267 | * |
||
268 | * @throws SyntaxError if the new template is invalid |
||
269 | */ |
||
270 | 2 | public function withTemplate($template): self |
|
271 | { |
||
272 | 2 | $template = $this->filterTemplate($template); |
|
273 | 2 | if ($template === $this->template) { |
|
274 | 2 | return $this; |
|
275 | } |
||
276 | |||
277 | 2 | $clone = clone $this; |
|
278 | 2 | $clone->template = $template; |
|
279 | 2 | $clone->parseExpressions(); |
|
280 | |||
281 | 2 | return $clone; |
|
282 | } |
||
283 | |||
284 | /** |
||
285 | * Returns the default values used to expand the template. |
||
286 | * |
||
287 | * The returned list only contains variables whose name is part of the current template. |
||
288 | * |
||
289 | * @return array<string,string|array> |
||
290 | */ |
||
291 | 2 | public function getDefaultVariables(): array |
|
292 | { |
||
293 | 2 | return $this->defaultVariables; |
|
294 | } |
||
295 | |||
296 | /** |
||
297 | * Returns a new instance with the updated default variables. |
||
298 | * |
||
299 | * This method MUST retain the state of the current instance, and return |
||
300 | * an instance that contains the modified default variables. |
||
301 | * |
||
302 | * If present, variables whose name is not part of the current template |
||
303 | * possible variable names are removed. |
||
304 | * |
||
305 | */ |
||
306 | 2 | public function withDefaultVariables(array $defaultDefaultVariables): self |
|
307 | { |
||
308 | 2 | $defaultDefaultVariables = $this->filterVariables($defaultDefaultVariables); |
|
309 | 2 | if ($defaultDefaultVariables === $this->defaultVariables) { |
|
310 | 2 | return $this; |
|
311 | } |
||
312 | |||
313 | 2 | $clone = clone $this; |
|
314 | 2 | $clone->defaultVariables = $defaultDefaultVariables; |
|
315 | |||
316 | 2 | return $clone; |
|
317 | } |
||
318 | |||
319 | /** |
||
320 | * @throws TemplateCanNotBeExpanded if the variable contains nested array values |
||
321 | * @throws UriException if the resulting expansion can not be converted to a UriInterface instance |
||
322 | */ |
||
323 | 154 | public function expand(array $variables = []): UriInterface |
|
324 | { |
||
325 | 154 | if ([] === $this->expressions) { |
|
326 | 2 | $this->cache['noExpression'] = $this->cache['noExpression'] ?? Uri::createFromString($this->template); |
|
327 | |||
328 | 2 | return $this->cache['noExpression']; |
|
329 | } |
||
330 | |||
331 | 152 | $this->variables = $this->filterVariables($variables) + $this->defaultVariables; |
|
332 | 152 | if ([] === $this->variables) { |
|
333 | 2 | $this->cache['noVariables'] = $this->cache['noVariables'] ?? Uri::createFromString( |
|
334 | 2 | preg_replace(self::REGEXP_EXPRESSION, '', $this->template) |
|
335 | ); |
||
336 | |||
337 | 2 | return $this->cache['noVariables']; |
|
338 | } |
||
339 | |||
340 | /** @var string $uri */ |
||
341 | 150 | $uri = preg_replace_callback(self::REGEXP_EXPRESSION, [$this, 'expandExpression'], $this->template); |
|
342 | |||
343 | 150 | return Uri::createFromString($uri); |
|
344 | } |
||
345 | |||
346 | /** |
||
347 | * Expands a single expression. |
||
348 | * |
||
349 | * @param array{expression:string, operator: string, variables:string} $foundExpression |
||
350 | * |
||
351 | * @throws TemplateCanNotBeExpanded if the variables is an array and a ":" modifier needs to be applied |
||
352 | * @throws TemplateCanNotBeExpanded if the variables contains nested array values |
||
353 | */ |
||
354 | 146 | private function expandExpression(array $foundExpression): string |
|
355 | { |
||
356 | 146 | $expression = $this->expressions[$foundExpression['expression']]; |
|
357 | 146 | $joiner = $expression['joiner']; |
|
358 | 146 | $useQuery = $expression['query']; |
|
359 | |||
360 | 146 | $parts = []; |
|
361 | /** @var array{name:string, modifier:string, position:string} $variable */ |
||
362 | 146 | foreach ($expression['variables'] as $variable) { |
|
363 | 146 | $parts[] = $this->expandVariable($variable, $expression['operator'], $joiner, $useQuery); |
|
364 | } |
||
365 | |||
366 | $nullFilter = static function ($value): bool { |
||
367 | 146 | return null !== $value && '' !== $value; |
|
368 | 146 | }; |
|
369 | |||
370 | 146 | $expanded = implode($joiner, array_filter($parts, $nullFilter)); |
|
371 | 146 | $prefix = $expression['prefix']; |
|
372 | 146 | if ('' !== $expanded && '' !== $prefix) { |
|
373 | 96 | return $prefix.$expanded; |
|
374 | } |
||
375 | |||
376 | 54 | return $expanded; |
|
377 | } |
||
378 | |||
379 | /** |
||
380 | * Expands an expression. |
||
381 | * |
||
382 | * @param array{name:string, modifier:string, position:string} $variable |
||
383 | * |
||
384 | * @throws TemplateCanNotBeExpanded if the variables is an array and a ":" modifier needs to be applied |
||
385 | * @throws TemplateCanNotBeExpanded if the variables contains nested array values |
||
386 | */ |
||
387 | 146 | private function expandVariable(array $variable, string $operator, string $joiner, bool $useQuery): string |
|
388 | { |
||
389 | 146 | $expanded = ''; |
|
390 | 146 | if (!isset($this->variables[$variable['name']])) { |
|
391 | 4 | return $expanded; |
|
392 | } |
||
393 | |||
394 | 144 | $value = $this->normalizeValue($this->variables[$variable['name']]); |
|
395 | 144 | $arguments = [$value, $variable, $operator]; |
|
396 | 144 | $method = 'expandString'; |
|
397 | 144 | $actualQuery = $useQuery; |
|
398 | 144 | if (is_array($value)) { |
|
399 | 74 | $arguments[] = $joiner; |
|
400 | 74 | $arguments[] = $useQuery; |
|
401 | 74 | $method = 'expandList'; |
|
402 | } |
||
403 | |||
404 | 144 | $expanded = $this->$method(...$arguments); |
|
405 | 144 | if (is_array($expanded)) { |
|
406 | 74 | [$expanded, $actualQuery] = $expanded; |
|
407 | } |
||
408 | |||
409 | 144 | if (!$actualQuery) { |
|
410 | 108 | return $expanded; |
|
411 | } |
||
412 | |||
413 | 38 | if ('&' !== $joiner && '' === $expanded) { |
|
414 | 2 | return $variable['name']; |
|
415 | } |
||
416 | |||
417 | 38 | return $variable['name'].'='.$expanded; |
|
418 | } |
||
419 | |||
420 | /** |
||
421 | * @param mixed $value the value to be expanded |
||
422 | * |
||
423 | * @throws \TypeError if the type is not supported |
||
424 | * |
||
425 | * @return string|array |
||
426 | */ |
||
427 | 8 | private function normalizeValue($value) |
|
428 | { |
||
429 | 8 | if (is_array($value)) { |
|
430 | 4 | return $value; |
|
431 | } |
||
432 | |||
433 | 8 | if (is_bool($value)) { |
|
434 | 2 | return true === $value ? '1' : '0'; |
|
435 | } |
||
436 | |||
437 | 6 | if (is_scalar($value) || method_exists($value, '__toString')) { |
|
438 | 4 | return (string) $value; |
|
439 | } |
||
440 | |||
441 | 2 | throw new \TypeError(sprintf('The variables must be a scalar or a stringable object `%s` given', gettype($value))); |
|
442 | } |
||
443 | |||
444 | /** |
||
445 | * Expands an expression using a string value. |
||
446 | */ |
||
447 | 76 | private function expandString(string $value, array $variable, string $operator): string |
|
448 | { |
||
449 | 76 | if (':' === $variable['modifier']) { |
|
450 | 22 | $value = substr($value, 0, $variable['position']); |
|
451 | } |
||
452 | |||
453 | 76 | $expanded = rawurlencode($value); |
|
454 | 76 | if ('+' === $operator || '#' === $operator) { |
|
455 | 26 | return $this->decodeReserved($expanded); |
|
456 | } |
||
457 | |||
458 | 52 | return $expanded; |
|
459 | } |
||
460 | |||
461 | /** |
||
462 | * Expands an expression using a list of values. |
||
463 | * |
||
464 | * @throws TemplateCanNotBeExpanded if the variables is an array and a ":" modifier needs to be applied |
||
465 | * @throws TemplateCanNotBeExpanded if the variables contains nested array values |
||
466 | * |
||
467 | * @return array{0:string, 1:bool} |
||
468 | */ |
||
469 | 82 | private function expandList(array $value, array $variable, string $operator, string $joiner, bool $useQuery): array |
|
470 | { |
||
471 | 82 | if ([] === $value) { |
|
472 | 4 | return ['', false]; |
|
473 | } |
||
474 | |||
475 | 78 | $isAssoc = $this->isAssoc($value); |
|
476 | 78 | $pairs = []; |
|
477 | 78 | if (':' === $variable['modifier']) { |
|
478 | 4 | throw TemplateCanNotBeExpanded::dueToUnableToProcessValueListWithPrefix($variable['name']); |
|
479 | } |
||
480 | |||
481 | /** @var string $key */ |
||
482 | 74 | foreach ($value as $key => $var) { |
|
483 | 74 | if ($isAssoc) { |
|
484 | 38 | if (is_array($var)) { |
|
485 | 2 | throw TemplateCanNotBeExpanded::dueToNestedListOfValue($key); |
|
486 | } |
||
487 | |||
488 | 36 | $key = rawurlencode((string) $key); |
|
489 | } |
||
490 | |||
491 | 72 | $var = rawurlencode((string) $var); |
|
492 | 72 | if ('+' === $operator || '#' === $operator) { |
|
493 | 16 | $var = $this->decodeReserved($var); |
|
494 | } |
||
495 | |||
496 | 72 | if ('*' === $variable['modifier']) { |
|
497 | 40 | if ($isAssoc) { |
|
498 | 20 | $var = $key.'='.$var; |
|
499 | 20 | } elseif ($key > 0 && $useQuery) { |
|
500 | 8 | $var = $variable['name'].'='.$var; |
|
501 | } |
||
502 | } |
||
503 | |||
504 | 72 | $pairs[$key] = $var; |
|
505 | } |
||
506 | |||
507 | 72 | if ('*' === $variable['modifier']) { |
|
508 | 40 | if ($isAssoc) { |
|
509 | // Don't prepend the value name when using the explode |
||
510 | // modifier with an associative array. |
||
511 | 20 | $useQuery = false; |
|
512 | } |
||
513 | |||
514 | 40 | return [implode($joiner, $pairs), $useQuery]; |
|
515 | } |
||
516 | |||
517 | 34 | if ($isAssoc) { |
|
518 | // When an associative array is encountered and the |
||
519 | // explode modifier is not set, then the result must be |
||
520 | // a comma separated list of keys followed by their |
||
521 | // respective values. |
||
522 | 16 | foreach ($pairs as $offset => &$data) { |
|
523 | 16 | $data = $offset.','.$data; |
|
524 | } |
||
525 | |||
526 | 16 | unset($data); |
|
527 | } |
||
528 | |||
529 | 34 | return [implode(',', $pairs), $useQuery]; |
|
530 | } |
||
531 | |||
532 | /** |
||
533 | * Determines if an array is associative. |
||
534 | * |
||
535 | * This makes the assumption that input arrays are sequences or hashes. |
||
536 | * This assumption is a tradeoff for accuracy in favor of speed, but it |
||
537 | * should work in almost every case where input is supplied for a URI |
||
538 | * template. |
||
539 | */ |
||
540 | 70 | private function isAssoc(array $array): bool |
|
541 | { |
||
542 | 70 | return [] !== $array && 0 !== array_keys($array)[0]; |
|
543 | } |
||
544 | |||
545 | /** |
||
546 | * Removes percent encoding on reserved characters (used with + and # modifiers). |
||
547 | */ |
||
548 | 42 | private function decodeReserved(string $str): string |
|
549 | { |
||
550 | 42 | static $delimiters = [ |
|
551 | ':', '/', '?', '#', '[', ']', '@', '!', '$', |
||
552 | '&', '\'', '(', ')', '*', '+', ',', ';', '=', |
||
553 | ]; |
||
554 | |||
555 | 42 | static $delimitersEncoded = [ |
|
556 | '%3A', '%2F', '%3F', '%23', '%5B', '%5D', '%40', '%21', '%24', |
||
557 | '%26', '%27', '%28', '%29', '%2A', '%2B', '%2C', '%3B', '%3D', |
||
558 | ]; |
||
559 | |||
560 | 42 | return str_replace($delimitersEncoded, $delimiters, $str); |
|
561 | } |
||
562 | } |
||
563 |