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