Ampache PHP Cross Reference Groupware Applications

Source: /modules/Symfony/Component/Routing/Route.php - 646 lines - 16089 bytes - Summary - Text - Print

   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   * @api
  21   */
  22  class Route implements \Serializable
  23  {
  24      /**
  25       * @var string
  26       */
  27      private $path = '/';
  28  
  29      /**
  30       * @var string
  31       */
  32      private $host = '';
  33  
  34      /**
  35       * @var array
  36       */
  37      private $schemes = array();
  38  
  39      /**
  40       * @var array
  41       */
  42      private $methods = array();
  43  
  44      /**
  45       * @var array
  46       */
  47      private $defaults = array();
  48  
  49      /**
  50       * @var array
  51       */
  52      private $requirements = array();
  53  
  54      /**
  55       * @var array
  56       */
  57      private $options = array();
  58  
  59      /**
  60       * @var null|CompiledRoute
  61       */
  62      private $compiled;
  63  
  64      private $condition;
  65  
  66      /**
  67       * Constructor.
  68       *
  69       * Available options:
  70       *
  71       *  * compiler_class: A class name able to compile this route instance (RouteCompiler by default)
  72       *
  73       * @param string       $path         The path pattern to match
  74       * @param array        $defaults     An array of default parameter values
  75       * @param array        $requirements An array of requirements for parameters (regexes)
  76       * @param array        $options      An array of options
  77       * @param string       $host         The host pattern to match
  78       * @param string|array $schemes      A required URI scheme or an array of restricted schemes
  79       * @param string|array $methods      A required HTTP method or an array of restricted methods
  80       * @param string       $condition    A condition that should evaluate to true for the route to match
  81       *
  82       * @api
  83       */
  84      public function __construct($path, array $defaults = array(), array $requirements = array(), array $options = array(), $host = '', $schemes = array(), $methods = array(), $condition = null)
  85      {
  86          $this->setPath($path);
  87          $this->setDefaults($defaults);
  88          $this->setRequirements($requirements);
  89          $this->setOptions($options);
  90          $this->setHost($host);
  91          // The conditions make sure that an initial empty $schemes/$methods does not override the corresponding requirement.
  92          // They can be removed when the BC layer is removed.
  93          if ($schemes) {
  94              $this->setSchemes($schemes);
  95          }
  96          if ($methods) {
  97              $this->setMethods($methods);
  98          }
  99          $this->setCondition($condition);
 100      }
 101  
 102      public function serialize()
 103      {
 104          return serialize(array(
 105              'path'         => $this->path,
 106              'host'         => $this->host,
 107              'defaults'     => $this->defaults,
 108              'requirements' => $this->requirements,
 109              'options'      => $this->options,
 110              'schemes'      => $this->schemes,
 111              'methods'      => $this->methods,
 112              'condition'    => $this->condition,
 113          ));
 114      }
 115  
 116      public function unserialize($data)
 117      {
 118          $data = unserialize($data);
 119          $this->path = $data['path'];
 120          $this->host = $data['host'];
 121          $this->defaults = $data['defaults'];
 122          $this->requirements = $data['requirements'];
 123          $this->options = $data['options'];
 124          $this->schemes = $data['schemes'];
 125          $this->methods = $data['methods'];
 126          $this->condition = $data['condition'];
 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 Boolean true if the scheme requirement exists, otherwise false
 256       */
 257      public function hasScheme($scheme)
 258      {
 259          $scheme = strtolower($scheme);
 260          foreach ($this->schemes as $requiredScheme) {
 261              if ($scheme === $requiredScheme) {
 262                  return true;
 263              }
 264          }
 265  
 266          return false;
 267      }
 268  
 269      /**
 270       * Returns the uppercased HTTP methods this route is restricted to.
 271       * So an empty array means that any method is allowed.
 272       *
 273       * @return array The schemes
 274       */
 275      public function getMethods()
 276      {
 277          return $this->methods;
 278      }
 279  
 280      /**
 281       * Sets the HTTP methods (e.g. 'POST') this route is restricted to.
 282       * So an empty array means that any method is allowed.
 283       *
 284       * This method implements a fluent interface.
 285       *
 286       * @param string|array $methods The method or an array of methods
 287       *
 288       * @return Route The current Route instance
 289       */
 290      public function setMethods($methods)
 291      {
 292          $this->methods = array_map('strtoupper', (array) $methods);
 293  
 294          // this is to keep BC and will be removed in a future version
 295          if ($this->methods) {
 296              $this->requirements['_method'] = implode('|', $this->methods);
 297          } else {
 298              unset($this->requirements['_method']);
 299          }
 300  
 301          $this->compiled = null;
 302  
 303          return $this;
 304      }
 305  
 306      /**
 307       * Returns the options.
 308       *
 309       * @return array The options
 310       */
 311      public function getOptions()
 312      {
 313          return $this->options;
 314      }
 315  
 316      /**
 317       * Sets the options.
 318       *
 319       * This method implements a fluent interface.
 320       *
 321       * @param array $options The options
 322       *
 323       * @return Route The current Route instance
 324       */
 325      public function setOptions(array $options)
 326      {
 327          $this->options = array(
 328              'compiler_class' => 'Symfony\\Component\\Routing\\RouteCompiler',
 329          );
 330  
 331          return $this->addOptions($options);
 332      }
 333  
 334      /**
 335       * Adds options.
 336       *
 337       * This method implements a fluent interface.
 338       *
 339       * @param array $options The options
 340       *
 341       * @return Route The current Route instance
 342       */
 343      public function addOptions(array $options)
 344      {
 345          foreach ($options as $name => $option) {
 346              $this->options[$name] = $option;
 347          }
 348          $this->compiled = null;
 349  
 350          return $this;
 351      }
 352  
 353      /**
 354       * Sets an option value.
 355       *
 356       * This method implements a fluent interface.
 357       *
 358       * @param string $name  An option name
 359       * @param mixed  $value The option value
 360       *
 361       * @return Route The current Route instance
 362       *
 363       * @api
 364       */
 365      public function setOption($name, $value)
 366      {
 367          $this->options[$name] = $value;
 368          $this->compiled = null;
 369  
 370          return $this;
 371      }
 372  
 373      /**
 374       * Get an option value.
 375       *
 376       * @param string $name An option name
 377       *
 378       * @return mixed The option value or null when not given
 379       */
 380      public function getOption($name)
 381      {
 382          return isset($this->options[$name]) ? $this->options[$name] : null;
 383      }
 384  
 385      /**
 386       * Checks if an option has been set
 387       *
 388       * @param string $name An option name
 389       *
 390       * @return Boolean true if the option is set, false otherwise
 391       */
 392      public function hasOption($name)
 393      {
 394          return array_key_exists($name, $this->options);
 395      }
 396  
 397      /**
 398       * Returns the defaults.
 399       *
 400       * @return array The defaults
 401       */
 402      public function getDefaults()
 403      {
 404          return $this->defaults;
 405      }
 406  
 407      /**
 408       * Sets the defaults.
 409       *
 410       * This method implements a fluent interface.
 411       *
 412       * @param array $defaults The defaults
 413       *
 414       * @return Route The current Route instance
 415       */
 416      public function setDefaults(array $defaults)
 417      {
 418          $this->defaults = array();
 419  
 420          return $this->addDefaults($defaults);
 421      }
 422  
 423      /**
 424       * Adds defaults.
 425       *
 426       * This method implements a fluent interface.
 427       *
 428       * @param array $defaults The defaults
 429       *
 430       * @return Route The current Route instance
 431       */
 432      public function addDefaults(array $defaults)
 433      {
 434          foreach ($defaults as $name => $default) {
 435              $this->defaults[$name] = $default;
 436          }
 437          $this->compiled = null;
 438  
 439          return $this;
 440      }
 441  
 442      /**
 443       * Gets a default value.
 444       *
 445       * @param string $name A variable name
 446       *
 447       * @return mixed The default value or null when not given
 448       */
 449      public function getDefault($name)
 450      {
 451          return isset($this->defaults[$name]) ? $this->defaults[$name] : null;
 452      }
 453  
 454      /**
 455       * Checks if a default value is set for the given variable.
 456       *
 457       * @param string $name A variable name
 458       *
 459       * @return Boolean true if the default value is set, false otherwise
 460       */
 461      public function hasDefault($name)
 462      {
 463          return array_key_exists($name, $this->defaults);
 464      }
 465  
 466      /**
 467       * Sets a default value.
 468       *
 469       * @param string $name    A variable name
 470       * @param mixed  $default The default value
 471       *
 472       * @return Route The current Route instance
 473       *
 474       * @api
 475       */
 476      public function setDefault($name, $default)
 477      {
 478          $this->defaults[$name] = $default;
 479          $this->compiled = null;
 480  
 481          return $this;
 482      }
 483  
 484      /**
 485       * Returns the requirements.
 486       *
 487       * @return array The requirements
 488       */
 489      public function getRequirements()
 490      {
 491          return $this->requirements;
 492      }
 493  
 494      /**
 495       * Sets the requirements.
 496       *
 497       * This method implements a fluent interface.
 498       *
 499       * @param array $requirements The requirements
 500       *
 501       * @return Route The current Route instance
 502       */
 503      public function setRequirements(array $requirements)
 504      {
 505          $this->requirements = array();
 506  
 507          return $this->addRequirements($requirements);
 508      }
 509  
 510      /**
 511       * Adds requirements.
 512       *
 513       * This method implements a fluent interface.
 514       *
 515       * @param array $requirements The requirements
 516       *
 517       * @return Route The current Route instance
 518       */
 519      public function addRequirements(array $requirements)
 520      {
 521          foreach ($requirements as $key => $regex) {
 522              $this->requirements[$key] = $this->sanitizeRequirement($key, $regex);
 523          }
 524          $this->compiled = null;
 525  
 526          return $this;
 527      }
 528  
 529      /**
 530       * Returns the requirement for the given key.
 531       *
 532       * @param string $key The key
 533       *
 534       * @return string|null The regex or null when not given
 535       */
 536      public function getRequirement($key)
 537      {
 538          return isset($this->requirements[$key]) ? $this->requirements[$key] : null;
 539      }
 540  
 541      /**
 542       * Checks if a requirement is set for the given key.
 543       *
 544       * @param string $key A variable name
 545       *
 546       * @return Boolean true if a requirement is specified, false otherwise
 547       */
 548      public function hasRequirement($key)
 549      {
 550          return array_key_exists($key, $this->requirements);
 551      }
 552  
 553      /**
 554       * Sets a requirement for the given key.
 555       *
 556       * @param string $key   The key
 557       * @param string $regex The regex
 558       *
 559       * @return Route The current Route instance
 560       *
 561       * @api
 562       */
 563      public function setRequirement($key, $regex)
 564      {
 565          $this->requirements[$key] = $this->sanitizeRequirement($key, $regex);
 566          $this->compiled = null;
 567  
 568          return $this;
 569      }
 570  
 571      /**
 572       * Returns the condition.
 573       *
 574       * @return string The condition
 575       */
 576      public function getCondition()
 577      {
 578          return $this->condition;
 579      }
 580  
 581      /**
 582       * Sets the condition.
 583       *
 584       * This method implements a fluent interface.
 585       *
 586       * @param string $condition The condition
 587       *
 588       * @return Route The current Route instance
 589       */
 590      public function setCondition($condition)
 591      {
 592          $this->condition = (string) $condition;
 593          $this->compiled = null;
 594  
 595          return $this;
 596      }
 597  
 598      /**
 599       * Compiles the route.
 600       *
 601       * @return CompiledRoute A CompiledRoute instance
 602       *
 603       * @throws \LogicException If the Route cannot be compiled because the
 604       *                         path or host pattern is invalid
 605       *
 606       * @see RouteCompiler which is responsible for the compilation process
 607       */
 608      public function compile()
 609      {
 610          if (null !== $this->compiled) {
 611              return $this->compiled;
 612          }
 613  
 614          $class = $this->getOption('compiler_class');
 615  
 616          return $this->compiled = $class::compile($this);
 617      }
 618  
 619      private function sanitizeRequirement($key, $regex)
 620      {
 621          if (!is_string($regex)) {
 622              throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" must be a string.', $key));
 623          }
 624  
 625          if ('' !== $regex && '^' === $regex[0]) {
 626              $regex = (string) substr($regex, 1); // returns false for a single character
 627          }
 628  
 629          if ('$' === substr($regex, -1)) {
 630              $regex = substr($regex, 0, -1);
 631          }
 632  
 633          if ('' === $regex) {
 634              throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" cannot be empty.', $key));
 635          }
 636  
 637          // this is to keep BC and will be removed in a future version
 638          if ('_scheme' === $key) {
 639              $this->setSchemes(explode('|', $regex));
 640          } elseif ('_method' === $key) {
 641              $this->setMethods(explode('|', $regex));
 642          }
 643  
 644          return $regex;
 645      }
 646  }

title

Description

title

Description

title

Description

title

title

Body