A Route describes a route and its parameters.
@author Fabien Potencier <fabien@symfony.com> @author Tobias Schultze <http://tobion.de>
@api
Expanded class hierarchy of Route
class Route implements \Serializable {
/**
* @var string
*/
private $path = '/';
/**
* @var string
*/
private $host = '';
/**
* @var array
*/
private $schemes = array();
/**
* @var array
*/
private $methods = array();
/**
* @var array
*/
private $defaults = array();
/**
* @var array
*/
private $requirements = array();
/**
* @var array
*/
private $options = array();
/**
* @var null|RouteCompiler
*/
private $compiled;
/**
* Constructor.
*
* Available options:
*
* * compiler_class: A class name able to compile this route instance (RouteCompiler by default)
*
* @param string $path The path pattern to match
* @param array $defaults An array of default parameter values
* @param array $requirements An array of requirements for parameters (regexes)
* @param array $options An array of options
* @param string $host The host pattern to match
* @param string|array $schemes A required URI scheme or an array of restricted schemes
* @param string|array $methods A required HTTP method or an array of restricted methods
*
* @api
*/
public function __construct($path, array $defaults = array(), array $requirements = array(), array $options = array(), $host = '', $schemes = array(), $methods = array()) {
$this
->setPath($path);
$this
->setDefaults($defaults);
$this
->setRequirements($requirements);
$this
->setOptions($options);
$this
->setHost($host);
// The conditions make sure that an initial empty $schemes/$methods does not override the corresponding requirement.
// They can be removed when the BC layer is removed.
if ($schemes) {
$this
->setSchemes($schemes);
}
if ($methods) {
$this
->setMethods($methods);
}
}
public function serialize() {
return serialize(array(
'path' => $this->path,
'host' => $this->host,
'defaults' => $this->defaults,
'requirements' => $this->requirements,
'options' => $this->options,
'schemes' => $this->schemes,
'methods' => $this->methods,
));
}
public function unserialize($data) {
$data = unserialize($data);
$this->path = $data['path'];
$this->host = $data['host'];
$this->defaults = $data['defaults'];
$this->requirements = $data['requirements'];
$this->options = $data['options'];
$this->schemes = $data['schemes'];
$this->methods = $data['methods'];
}
/**
* Returns the pattern for the path.
*
* @return string The pattern
*
* @deprecated Deprecated in 2.2, to be removed in 3.0. Use getPath instead.
*/
public function getPattern() {
return $this->path;
}
/**
* Sets the pattern for the path.
*
* This method implements a fluent interface.
*
* @param string $pattern The path pattern
*
* @return Route The current Route instance
*
* @deprecated Deprecated in 2.2, to be removed in 3.0. Use setPath instead.
*/
public function setPattern($pattern) {
return $this
->setPath($pattern);
}
/**
* Returns the pattern for the path.
*
* @return string The path pattern
*/
public function getPath() {
return $this->path;
}
/**
* Sets the pattern for the path.
*
* This method implements a fluent interface.
*
* @param string $pattern The path pattern
*
* @return Route The current Route instance
*/
public function setPath($pattern) {
// A pattern must start with a slash and must not have multiple slashes at the beginning because the
// generated path for this route would be confused with a network path, e.g. '//domain.com/path'.
$this->path = '/' . ltrim(trim($pattern), '/');
$this->compiled = null;
return $this;
}
/**
* Returns the pattern for the host.
*
* @return string The host pattern
*/
public function getHost() {
return $this->host;
}
/**
* Sets the pattern for the host.
*
* This method implements a fluent interface.
*
* @param string $pattern The host pattern
*
* @return Route The current Route instance
*/
public function setHost($pattern) {
$this->host = (string) $pattern;
$this->compiled = null;
return $this;
}
/**
* Returns the lowercased schemes this route is restricted to.
* So an empty array means that any scheme is allowed.
*
* @return array The schemes
*/
public function getSchemes() {
return $this->schemes;
}
/**
* Sets the schemes (e.g. 'https') this route is restricted to.
* So an empty array means that any scheme is allowed.
*
* This method implements a fluent interface.
*
* @param string|array $schemes The scheme or an array of schemes
*
* @return Route The current Route instance
*/
public function setSchemes($schemes) {
$this->schemes = array_map('strtolower', (array) $schemes);
// this is to keep BC and will be removed in a future version
if ($this->schemes) {
$this->requirements['_scheme'] = implode('|', $this->schemes);
}
else {
unset($this->requirements['_scheme']);
}
$this->compiled = null;
return $this;
}
/**
* Returns the uppercased HTTP methods this route is restricted to.
* So an empty array means that any method is allowed.
*
* @return array The schemes
*/
public function getMethods() {
return $this->methods;
}
/**
* Sets the HTTP methods (e.g. 'POST') this route is restricted to.
* So an empty array means that any method is allowed.
*
* This method implements a fluent interface.
*
* @param string|array $methods The method or an array of methods
*
* @return Route The current Route instance
*/
public function setMethods($methods) {
$this->methods = array_map('strtoupper', (array) $methods);
// this is to keep BC and will be removed in a future version
if ($this->methods) {
$this->requirements['_method'] = implode('|', $this->methods);
}
else {
unset($this->requirements['_method']);
}
$this->compiled = null;
return $this;
}
/**
* Returns the options.
*
* @return array The options
*/
public function getOptions() {
return $this->options;
}
/**
* Sets the options.
*
* This method implements a fluent interface.
*
* @param array $options The options
*
* @return Route The current Route instance
*/
public function setOptions(array $options) {
$this->options = array(
'compiler_class' => 'Symfony\\Component\\Routing\\RouteCompiler',
);
return $this
->addOptions($options);
}
/**
* Adds options.
*
* This method implements a fluent interface.
*
* @param array $options The options
*
* @return Route The current Route instance
*/
public function addOptions(array $options) {
foreach ($options as $name => $option) {
$this->options[$name] = $option;
}
$this->compiled = null;
return $this;
}
/**
* Sets an option value.
*
* This method implements a fluent interface.
*
* @param string $name An option name
* @param mixed $value The option value
*
* @return Route The current Route instance
*
* @api
*/
public function setOption($name, $value) {
$this->options[$name] = $value;
$this->compiled = null;
return $this;
}
/**
* Get an option value.
*
* @param string $name An option name
*
* @return mixed The option value or null when not given
*/
public function getOption($name) {
return isset($this->options[$name]) ? $this->options[$name] : null;
}
/**
* Checks if an option has been set
*
* @param string $name An option name
*
* @return Boolean true if the option is set, false otherwise
*/
public function hasOption($name) {
return array_key_exists($name, $this->options);
}
/**
* Returns the defaults.
*
* @return array The defaults
*/
public function getDefaults() {
return $this->defaults;
}
/**
* Sets the defaults.
*
* This method implements a fluent interface.
*
* @param array $defaults The defaults
*
* @return Route The current Route instance
*/
public function setDefaults(array $defaults) {
$this->defaults = array();
return $this
->addDefaults($defaults);
}
/**
* Adds defaults.
*
* This method implements a fluent interface.
*
* @param array $defaults The defaults
*
* @return Route The current Route instance
*/
public function addDefaults(array $defaults) {
foreach ($defaults as $name => $default) {
$this->defaults[$name] = $default;
}
$this->compiled = null;
return $this;
}
/**
* Gets a default value.
*
* @param string $name A variable name
*
* @return mixed The default value or null when not given
*/
public function getDefault($name) {
return isset($this->defaults[$name]) ? $this->defaults[$name] : null;
}
/**
* Checks if a default value is set for the given variable.
*
* @param string $name A variable name
*
* @return Boolean true if the default value is set, false otherwise
*/
public function hasDefault($name) {
return array_key_exists($name, $this->defaults);
}
/**
* Sets a default value.
*
* @param string $name A variable name
* @param mixed $default The default value
*
* @return Route The current Route instance
*
* @api
*/
public function setDefault($name, $default) {
$this->defaults[$name] = $default;
$this->compiled = null;
return $this;
}
/**
* Returns the requirements.
*
* @return array The requirements
*/
public function getRequirements() {
return $this->requirements;
}
/**
* Sets the requirements.
*
* This method implements a fluent interface.
*
* @param array $requirements The requirements
*
* @return Route The current Route instance
*/
public function setRequirements(array $requirements) {
$this->requirements = array();
return $this
->addRequirements($requirements);
}
/**
* Adds requirements.
*
* This method implements a fluent interface.
*
* @param array $requirements The requirements
*
* @return Route The current Route instance
*/
public function addRequirements(array $requirements) {
foreach ($requirements as $key => $regex) {
$this->requirements[$key] = $this
->sanitizeRequirement($key, $regex);
}
$this->compiled = null;
return $this;
}
/**
* Returns the requirement for the given key.
*
* @param string $key The key
*
* @return string|null The regex or null when not given
*/
public function getRequirement($key) {
return isset($this->requirements[$key]) ? $this->requirements[$key] : null;
}
/**
* Checks if a requirement is set for the given key.
*
* @param string $key A variable name
*
* @return Boolean true if a requirement is specified, false otherwise
*/
public function hasRequirement($key) {
return array_key_exists($key, $this->requirements);
}
/**
* Sets a requirement for the given key.
*
* @param string $key The key
* @param string $regex The regex
*
* @return Route The current Route instance
*
* @api
*/
public function setRequirement($key, $regex) {
$this->requirements[$key] = $this
->sanitizeRequirement($key, $regex);
$this->compiled = null;
return $this;
}
/**
* Compiles the route.
*
* @return CompiledRoute A CompiledRoute instance
*
* @throws \LogicException If the Route cannot be compiled because the
* path or host pattern is invalid
*
* @see RouteCompiler which is responsible for the compilation process
*/
public function compile() {
if (null !== $this->compiled) {
return $this->compiled;
}
$class = $this
->getOption('compiler_class');
return $this->compiled = $class::compile($this);
}
private function sanitizeRequirement($key, $regex) {
if (!is_string($regex)) {
throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" must be a string.', $key));
}
if ('' !== $regex && '^' === $regex[0]) {
$regex = (string) substr($regex, 1);
// returns false for a single character
}
if ('$' === substr($regex, -1)) {
$regex = substr($regex, 0, -1);
}
if ('' === $regex) {
throw new \InvalidArgumentException(sprintf('Routing requirement for "%s" cannot be empty.', $key));
}
// this is to keep BC and will be removed in a future version
if ('_scheme' === $key) {
$this
->setSchemes(explode('|', $regex));
}
elseif ('_method' === $key) {
$this
->setMethods(explode('|', $regex));
}
return $regex;
}
}
Name | Modifiers | Type | Description | Overrides |
---|---|---|---|---|
Route:: |
public | function | Returns the defaults. | 1 |
Route:: |
public | function | Returns the requirement for the given key. | 1 |
Route:: |
public | function | Constructor. | |
Route:: |
public | function | ||
Route:: |
public | function | ||
Route:: |
public | function | Returns the pattern for the path. | |
Route:: |
public | function | Sets the pattern for the path. | |
Route:: |
public | function | Returns the pattern for the path. | |
Route:: |
public | function | Sets the pattern for the path. | |
Route:: |
public | function | Returns the pattern for the host. | |
Route:: |
public | function | Sets the pattern for the host. | |
Route:: |
public | function | Returns the lowercased schemes this route is restricted to. So an empty array means that any scheme is allowed. | |
Route:: |
public | function | Sets the schemes (e.g. 'https') this route is restricted to. So an empty array means that any scheme is allowed. | |
Route:: |
public | function | Returns the uppercased HTTP methods this route is restricted to. So an empty array means that any method is allowed. | |
Route:: |
public | function | Sets the HTTP methods (e.g. 'POST') this route is restricted to. So an empty array means that any method is allowed. | |
Route:: |
public | function | Returns the options. | |
Route:: |
public | function | Sets the options. | |
Route:: |
public | function | Adds options. | |
Route:: |
public | function | Sets an option value. | |
Route:: |
public | function | Get an option value. | |
Route:: |
public | function | Checks if an option has been set | |
Route:: |
public | function | Sets the defaults. | |
Route:: |
public | function | Adds defaults. | |
Route:: |
public | function | Gets a default value. | |
Route:: |
public | function | Checks if a default value is set for the given variable. | |
Route:: |
public | function | Sets a default value. | |
Route:: |
public | function | Returns the requirements. | |
Route:: |
public | function | Sets the requirements. | |
Route:: |
public | function | Adds requirements. | |
Route:: |
public | function | Checks if a requirement is set for the given key. | |
Route:: |
public | function | Sets a requirement for the given key. | |
Route:: |
public | function | Compiles the route. | |
Route:: |
private | function | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property | ||
Route:: |
private | property |