[Summary view] [Print] [Text view]

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