annotate vendor/symfony/routing/Route.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /*
Chris@0 4 * This file is part of the Symfony package.
Chris@0 5 *
Chris@0 6 * (c) Fabien Potencier <fabien@symfony.com>
Chris@0 7 *
Chris@0 8 * For the full copyright and license information, please view the LICENSE
Chris@0 9 * file that was distributed with this source code.
Chris@0 10 */
Chris@0 11
Chris@0 12 namespace Symfony\Component\Routing;
Chris@0 13
Chris@0 14 /**
Chris@0 15 * A Route describes a route and its parameters.
Chris@0 16 *
Chris@0 17 * @author Fabien Potencier <fabien@symfony.com>
Chris@0 18 * @author Tobias Schultze <http://tobion.de>
Chris@0 19 */
Chris@0 20 class Route implements \Serializable
Chris@0 21 {
Chris@0 22 private $path = '/';
Chris@0 23 private $host = '';
Chris@17 24 private $schemes = [];
Chris@17 25 private $methods = [];
Chris@17 26 private $defaults = [];
Chris@17 27 private $requirements = [];
Chris@17 28 private $options = [];
Chris@14 29 private $condition = '';
Chris@0 30
Chris@0 31 /**
Chris@17 32 * @var CompiledRoute|null
Chris@0 33 */
Chris@0 34 private $compiled;
Chris@0 35
Chris@0 36 /**
Chris@0 37 * Constructor.
Chris@0 38 *
Chris@0 39 * Available options:
Chris@0 40 *
Chris@0 41 * * compiler_class: A class name able to compile this route instance (RouteCompiler by default)
Chris@0 42 * * utf8: Whether UTF-8 matching is enforced ot not
Chris@0 43 *
Chris@14 44 * @param string $path The path pattern to match
Chris@14 45 * @param array $defaults An array of default parameter values
Chris@14 46 * @param array $requirements An array of requirements for parameters (regexes)
Chris@14 47 * @param array $options An array of options
Chris@14 48 * @param string $host The host pattern to match
Chris@14 49 * @param string|string[] $schemes A required URI scheme or an array of restricted schemes
Chris@14 50 * @param string|string[] $methods A required HTTP method or an array of restricted methods
Chris@14 51 * @param string $condition A condition that should evaluate to true for the route to match
Chris@0 52 */
Chris@17 53 public function __construct($path, array $defaults = [], array $requirements = [], array $options = [], $host = '', $schemes = [], $methods = [], $condition = '')
Chris@0 54 {
Chris@0 55 $this->setPath($path);
Chris@0 56 $this->setDefaults($defaults);
Chris@0 57 $this->setRequirements($requirements);
Chris@0 58 $this->setOptions($options);
Chris@0 59 $this->setHost($host);
Chris@0 60 $this->setSchemes($schemes);
Chris@0 61 $this->setMethods($methods);
Chris@0 62 $this->setCondition($condition);
Chris@0 63 }
Chris@0 64
Chris@0 65 /**
Chris@0 66 * {@inheritdoc}
Chris@0 67 */
Chris@0 68 public function serialize()
Chris@0 69 {
Chris@17 70 return serialize([
Chris@0 71 'path' => $this->path,
Chris@0 72 'host' => $this->host,
Chris@0 73 'defaults' => $this->defaults,
Chris@0 74 'requirements' => $this->requirements,
Chris@0 75 'options' => $this->options,
Chris@0 76 'schemes' => $this->schemes,
Chris@0 77 'methods' => $this->methods,
Chris@0 78 'condition' => $this->condition,
Chris@0 79 'compiled' => $this->compiled,
Chris@17 80 ]);
Chris@0 81 }
Chris@0 82
Chris@0 83 /**
Chris@0 84 * {@inheritdoc}
Chris@0 85 */
Chris@0 86 public function unserialize($serialized)
Chris@0 87 {
Chris@0 88 $data = unserialize($serialized);
Chris@0 89 $this->path = $data['path'];
Chris@0 90 $this->host = $data['host'];
Chris@0 91 $this->defaults = $data['defaults'];
Chris@0 92 $this->requirements = $data['requirements'];
Chris@0 93 $this->options = $data['options'];
Chris@0 94 $this->schemes = $data['schemes'];
Chris@0 95 $this->methods = $data['methods'];
Chris@0 96
Chris@0 97 if (isset($data['condition'])) {
Chris@0 98 $this->condition = $data['condition'];
Chris@0 99 }
Chris@0 100 if (isset($data['compiled'])) {
Chris@0 101 $this->compiled = $data['compiled'];
Chris@0 102 }
Chris@0 103 }
Chris@0 104
Chris@0 105 /**
Chris@0 106 * Returns the pattern for the path.
Chris@0 107 *
Chris@0 108 * @return string The path pattern
Chris@0 109 */
Chris@0 110 public function getPath()
Chris@0 111 {
Chris@0 112 return $this->path;
Chris@0 113 }
Chris@0 114
Chris@0 115 /**
Chris@0 116 * Sets the pattern for the path.
Chris@0 117 *
Chris@0 118 * This method implements a fluent interface.
Chris@0 119 *
Chris@0 120 * @param string $pattern The path pattern
Chris@0 121 *
Chris@0 122 * @return $this
Chris@0 123 */
Chris@0 124 public function setPath($pattern)
Chris@0 125 {
Chris@0 126 // A pattern must start with a slash and must not have multiple slashes at the beginning because the
Chris@0 127 // generated path for this route would be confused with a network path, e.g. '//domain.com/path'.
Chris@0 128 $this->path = '/'.ltrim(trim($pattern), '/');
Chris@0 129 $this->compiled = null;
Chris@0 130
Chris@0 131 return $this;
Chris@0 132 }
Chris@0 133
Chris@0 134 /**
Chris@0 135 * Returns the pattern for the host.
Chris@0 136 *
Chris@0 137 * @return string The host pattern
Chris@0 138 */
Chris@0 139 public function getHost()
Chris@0 140 {
Chris@0 141 return $this->host;
Chris@0 142 }
Chris@0 143
Chris@0 144 /**
Chris@0 145 * Sets the pattern for the host.
Chris@0 146 *
Chris@0 147 * This method implements a fluent interface.
Chris@0 148 *
Chris@0 149 * @param string $pattern The host pattern
Chris@0 150 *
Chris@0 151 * @return $this
Chris@0 152 */
Chris@0 153 public function setHost($pattern)
Chris@0 154 {
Chris@0 155 $this->host = (string) $pattern;
Chris@0 156 $this->compiled = null;
Chris@0 157
Chris@0 158 return $this;
Chris@0 159 }
Chris@0 160
Chris@0 161 /**
Chris@0 162 * Returns the lowercased schemes this route is restricted to.
Chris@0 163 * So an empty array means that any scheme is allowed.
Chris@0 164 *
Chris@14 165 * @return string[] The schemes
Chris@0 166 */
Chris@0 167 public function getSchemes()
Chris@0 168 {
Chris@0 169 return $this->schemes;
Chris@0 170 }
Chris@0 171
Chris@0 172 /**
Chris@0 173 * Sets the schemes (e.g. 'https') this route is restricted to.
Chris@0 174 * So an empty array means that any scheme is allowed.
Chris@0 175 *
Chris@0 176 * This method implements a fluent interface.
Chris@0 177 *
Chris@14 178 * @param string|string[] $schemes The scheme or an array of schemes
Chris@0 179 *
Chris@0 180 * @return $this
Chris@0 181 */
Chris@0 182 public function setSchemes($schemes)
Chris@0 183 {
Chris@0 184 $this->schemes = array_map('strtolower', (array) $schemes);
Chris@0 185 $this->compiled = null;
Chris@0 186
Chris@0 187 return $this;
Chris@0 188 }
Chris@0 189
Chris@0 190 /**
Chris@0 191 * Checks if a scheme requirement has been set.
Chris@0 192 *
Chris@0 193 * @param string $scheme
Chris@0 194 *
Chris@0 195 * @return bool true if the scheme requirement exists, otherwise false
Chris@0 196 */
Chris@0 197 public function hasScheme($scheme)
Chris@0 198 {
Chris@17 199 return \in_array(strtolower($scheme), $this->schemes, true);
Chris@0 200 }
Chris@0 201
Chris@0 202 /**
Chris@0 203 * Returns the uppercased HTTP methods this route is restricted to.
Chris@0 204 * So an empty array means that any method is allowed.
Chris@0 205 *
Chris@14 206 * @return string[] The methods
Chris@0 207 */
Chris@0 208 public function getMethods()
Chris@0 209 {
Chris@0 210 return $this->methods;
Chris@0 211 }
Chris@0 212
Chris@0 213 /**
Chris@0 214 * Sets the HTTP methods (e.g. 'POST') this route is restricted to.
Chris@0 215 * So an empty array means that any method is allowed.
Chris@0 216 *
Chris@0 217 * This method implements a fluent interface.
Chris@0 218 *
Chris@14 219 * @param string|string[] $methods The method or an array of methods
Chris@0 220 *
Chris@0 221 * @return $this
Chris@0 222 */
Chris@0 223 public function setMethods($methods)
Chris@0 224 {
Chris@0 225 $this->methods = array_map('strtoupper', (array) $methods);
Chris@0 226 $this->compiled = null;
Chris@0 227
Chris@0 228 return $this;
Chris@0 229 }
Chris@0 230
Chris@0 231 /**
Chris@0 232 * Returns the options.
Chris@0 233 *
Chris@0 234 * @return array The options
Chris@0 235 */
Chris@0 236 public function getOptions()
Chris@0 237 {
Chris@0 238 return $this->options;
Chris@0 239 }
Chris@0 240
Chris@0 241 /**
Chris@0 242 * Sets the options.
Chris@0 243 *
Chris@0 244 * This method implements a fluent interface.
Chris@0 245 *
Chris@0 246 * @param array $options The options
Chris@0 247 *
Chris@0 248 * @return $this
Chris@0 249 */
Chris@0 250 public function setOptions(array $options)
Chris@0 251 {
Chris@17 252 $this->options = [
Chris@0 253 'compiler_class' => 'Symfony\\Component\\Routing\\RouteCompiler',
Chris@17 254 ];
Chris@0 255
Chris@0 256 return $this->addOptions($options);
Chris@0 257 }
Chris@0 258
Chris@0 259 /**
Chris@0 260 * Adds options.
Chris@0 261 *
Chris@0 262 * This method implements a fluent interface.
Chris@0 263 *
Chris@0 264 * @param array $options The options
Chris@0 265 *
Chris@0 266 * @return $this
Chris@0 267 */
Chris@0 268 public function addOptions(array $options)
Chris@0 269 {
Chris@0 270 foreach ($options as $name => $option) {
Chris@0 271 $this->options[$name] = $option;
Chris@0 272 }
Chris@0 273 $this->compiled = null;
Chris@0 274
Chris@0 275 return $this;
Chris@0 276 }
Chris@0 277
Chris@0 278 /**
Chris@0 279 * Sets an option value.
Chris@0 280 *
Chris@0 281 * This method implements a fluent interface.
Chris@0 282 *
Chris@0 283 * @param string $name An option name
Chris@0 284 * @param mixed $value The option value
Chris@0 285 *
Chris@0 286 * @return $this
Chris@0 287 */
Chris@0 288 public function setOption($name, $value)
Chris@0 289 {
Chris@0 290 $this->options[$name] = $value;
Chris@0 291 $this->compiled = null;
Chris@0 292
Chris@0 293 return $this;
Chris@0 294 }
Chris@0 295
Chris@0 296 /**
Chris@0 297 * Get an option value.
Chris@0 298 *
Chris@0 299 * @param string $name An option name
Chris@0 300 *
Chris@0 301 * @return mixed The option value or null when not given
Chris@0 302 */
Chris@0 303 public function getOption($name)
Chris@0 304 {
Chris@0 305 return isset($this->options[$name]) ? $this->options[$name] : null;
Chris@0 306 }
Chris@0 307
Chris@0 308 /**
Chris@0 309 * Checks if an option has been set.
Chris@0 310 *
Chris@0 311 * @param string $name An option name
Chris@0 312 *
Chris@0 313 * @return bool true if the option is set, false otherwise
Chris@0 314 */
Chris@0 315 public function hasOption($name)
Chris@0 316 {
Chris@18 317 return \array_key_exists($name, $this->options);
Chris@0 318 }
Chris@0 319
Chris@0 320 /**
Chris@0 321 * Returns the defaults.
Chris@0 322 *
Chris@0 323 * @return array The defaults
Chris@0 324 */
Chris@0 325 public function getDefaults()
Chris@0 326 {
Chris@0 327 return $this->defaults;
Chris@0 328 }
Chris@0 329
Chris@0 330 /**
Chris@0 331 * Sets the defaults.
Chris@0 332 *
Chris@0 333 * This method implements a fluent interface.
Chris@0 334 *
Chris@0 335 * @param array $defaults The defaults
Chris@0 336 *
Chris@0 337 * @return $this
Chris@0 338 */
Chris@0 339 public function setDefaults(array $defaults)
Chris@0 340 {
Chris@17 341 $this->defaults = [];
Chris@0 342
Chris@0 343 return $this->addDefaults($defaults);
Chris@0 344 }
Chris@0 345
Chris@0 346 /**
Chris@0 347 * Adds defaults.
Chris@0 348 *
Chris@0 349 * This method implements a fluent interface.
Chris@0 350 *
Chris@0 351 * @param array $defaults The defaults
Chris@0 352 *
Chris@0 353 * @return $this
Chris@0 354 */
Chris@0 355 public function addDefaults(array $defaults)
Chris@0 356 {
Chris@0 357 foreach ($defaults as $name => $default) {
Chris@0 358 $this->defaults[$name] = $default;
Chris@0 359 }
Chris@0 360 $this->compiled = null;
Chris@0 361
Chris@0 362 return $this;
Chris@0 363 }
Chris@0 364
Chris@0 365 /**
Chris@0 366 * Gets a default value.
Chris@0 367 *
Chris@0 368 * @param string $name A variable name
Chris@0 369 *
Chris@0 370 * @return mixed The default value or null when not given
Chris@0 371 */
Chris@0 372 public function getDefault($name)
Chris@0 373 {
Chris@0 374 return isset($this->defaults[$name]) ? $this->defaults[$name] : null;
Chris@0 375 }
Chris@0 376
Chris@0 377 /**
Chris@0 378 * Checks if a default value is set for the given variable.
Chris@0 379 *
Chris@0 380 * @param string $name A variable name
Chris@0 381 *
Chris@0 382 * @return bool true if the default value is set, false otherwise
Chris@0 383 */
Chris@0 384 public function hasDefault($name)
Chris@0 385 {
Chris@18 386 return \array_key_exists($name, $this->defaults);
Chris@0 387 }
Chris@0 388
Chris@0 389 /**
Chris@0 390 * Sets a default value.
Chris@0 391 *
Chris@0 392 * @param string $name A variable name
Chris@0 393 * @param mixed $default The default value
Chris@0 394 *
Chris@0 395 * @return $this
Chris@0 396 */
Chris@0 397 public function setDefault($name, $default)
Chris@0 398 {
Chris@0 399 $this->defaults[$name] = $default;
Chris@0 400 $this->compiled = null;
Chris@0 401
Chris@0 402 return $this;
Chris@0 403 }
Chris@0 404
Chris@0 405 /**
Chris@0 406 * Returns the requirements.
Chris@0 407 *
Chris@0 408 * @return array The requirements
Chris@0 409 */
Chris@0 410 public function getRequirements()
Chris@0 411 {
Chris@0 412 return $this->requirements;
Chris@0 413 }
Chris@0 414
Chris@0 415 /**
Chris@0 416 * Sets the requirements.
Chris@0 417 *
Chris@0 418 * This method implements a fluent interface.
Chris@0 419 *
Chris@0 420 * @param array $requirements The requirements
Chris@0 421 *
Chris@0 422 * @return $this
Chris@0 423 */
Chris@0 424 public function setRequirements(array $requirements)
Chris@0 425 {
Chris@17 426 $this->requirements = [];
Chris@0 427
Chris@0 428 return $this->addRequirements($requirements);
Chris@0 429 }
Chris@0 430
Chris@0 431 /**
Chris@0 432 * Adds requirements.
Chris@0 433 *
Chris@0 434 * This method implements a fluent interface.
Chris@0 435 *
Chris@0 436 * @param array $requirements The requirements
Chris@0 437 *
Chris@0 438 * @return $this
Chris@0 439 */
Chris@0 440 public function addRequirements(array $requirements)
Chris@0 441 {
Chris@0 442 foreach ($requirements as $key => $regex) {
Chris@0 443 $this->requirements[$key] = $this->sanitizeRequirement($key, $regex);
Chris@0 444 }
Chris@0 445 $this->compiled = null;
Chris@0 446
Chris@0 447 return $this;
Chris@0 448 }
Chris@0 449
Chris@0 450 /**
Chris@0 451 * Returns the requirement for the given key.
Chris@0 452 *
Chris@0 453 * @param string $key The key
Chris@0 454 *
Chris@0 455 * @return string|null The regex or null when not given
Chris@0 456 */
Chris@0 457 public function getRequirement($key)
Chris@0 458 {
Chris@0 459 return isset($this->requirements[$key]) ? $this->requirements[$key] : null;
Chris@0 460 }
Chris@0 461
Chris@0 462 /**
Chris@0 463 * Checks if a requirement is set for the given key.
Chris@0 464 *
Chris@0 465 * @param string $key A variable name
Chris@0 466 *
Chris@0 467 * @return bool true if a requirement is specified, false otherwise
Chris@0 468 */
Chris@0 469 public function hasRequirement($key)
Chris@0 470 {
Chris@18 471 return \array_key_exists($key, $this->requirements);
Chris@0 472 }
Chris@0 473
Chris@0 474 /**
Chris@0 475 * Sets a requirement for the given key.
Chris@0 476 *
Chris@0 477 * @param string $key The key
Chris@0 478 * @param string $regex The regex
Chris@0 479 *
Chris@0 480 * @return $this
Chris@0 481 */
Chris@0 482 public function setRequirement($key, $regex)
Chris@0 483 {
Chris@0 484 $this->requirements[$key] = $this->sanitizeRequirement($key, $regex);
Chris@0 485 $this->compiled = null;
Chris@0 486
Chris@0 487 return $this;
Chris@0 488 }
Chris@0 489
Chris@0 490 /**
Chris@0 491 * Returns the condition.
Chris@0 492 *
Chris@0 493 * @return string The condition
Chris@0 494 */
Chris@0 495 public function getCondition()
Chris@0 496 {
Chris@0 497 return $this->condition;
Chris@0 498 }
Chris@0 499
Chris@0 500 /**
Chris@0 501 * Sets the condition.
Chris@0 502 *
Chris@0 503 * This method implements a fluent interface.
Chris@0 504 *
Chris@0 505 * @param string $condition The condition
Chris@0 506 *
Chris@0 507 * @return $this
Chris@0 508 */
Chris@0 509 public function setCondition($condition)
Chris@0 510 {
Chris@0 511 $this->condition = (string) $condition;
Chris@0 512 $this->compiled = null;
Chris@0 513
Chris@0 514 return $this;
Chris@0 515 }
Chris@0 516
Chris@0 517 /**
Chris@0 518 * Compiles the route.
Chris@0 519 *
Chris@0 520 * @return CompiledRoute A CompiledRoute instance
Chris@0 521 *
Chris@0 522 * @throws \LogicException If the Route cannot be compiled because the
Chris@0 523 * path or host pattern is invalid
Chris@0 524 *
Chris@0 525 * @see RouteCompiler which is responsible for the compilation process
Chris@0 526 */
Chris@0 527 public function compile()
Chris@0 528 {
Chris@0 529 if (null !== $this->compiled) {
Chris@0 530 return $this->compiled;
Chris@0 531 }
Chris@0 532
Chris@0 533 $class = $this->getOption('compiler_class');
Chris@0 534
Chris@0 535 return $this->compiled = $class::compile($this);
Chris@0 536 }
Chris@0 537
Chris@0 538 private function sanitizeRequirement($key, $regex)
Chris@0 539 {
Chris@17 540 if (!\is_string($regex)) {
Chris@0 541 throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" must be a string.', $key));
Chris@0 542 }
Chris@0 543
Chris@0 544 if ('' !== $regex && '^' === $regex[0]) {
Chris@0 545 $regex = (string) substr($regex, 1); // returns false for a single character
Chris@0 546 }
Chris@0 547
Chris@0 548 if ('$' === substr($regex, -1)) {
Chris@0 549 $regex = substr($regex, 0, -1);
Chris@0 550 }
Chris@0 551
Chris@0 552 if ('' === $regex) {
Chris@0 553 throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" cannot be empty.', $key));
Chris@0 554 }
Chris@0 555
Chris@0 556 return $regex;
Chris@0 557 }
Chris@0 558 }