Route.php 14 KB

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