[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  use Symfony\Component\Config\Resource\ResourceInterface;
  15  
  16  /**
  17   * A RouteCollection represents a set of Route instances.
  18   *
  19   * When adding a route at the end of the collection, an existing route
  20   * with the same name is removed first. So there can only be one route
  21   * with a given name.
  22   *
  23   * @author Fabien Potencier <fabien@symfony.com>
  24   * @author Tobias Schultze <http://tobion.de>
  25   */
  26  class RouteCollection implements \IteratorAggregate, \Countable
  27  {
  28      /**
  29       * @var Route[]
  30       */
  31      private $routes = array();
  32  
  33      /**
  34       * @var array
  35       */
  36      private $resources = array();
  37  
  38      public function __clone()
  39      {
  40          foreach ($this->routes as $name => $route) {
  41              $this->routes[$name] = clone $route;
  42          }
  43      }
  44  
  45      /**
  46       * Gets the current RouteCollection as an Iterator that includes all routes.
  47       *
  48       * It implements \IteratorAggregate.
  49       *
  50       * @see all()
  51       *
  52       * @return \ArrayIterator|Route[] An \ArrayIterator object for iterating over routes
  53       */
  54      public function getIterator()
  55      {
  56          return new \ArrayIterator($this->routes);
  57      }
  58  
  59      /**
  60       * Gets the number of Routes in this collection.
  61       *
  62       * @return int The number of routes
  63       */
  64      public function count()
  65      {
  66          return \count($this->routes);
  67      }
  68  
  69      /**
  70       * Adds a route.
  71       *
  72       * @param string $name  The route name
  73       * @param Route  $route A Route instance
  74       */
  75      public function add($name, Route $route)
  76      {
  77          unset($this->routes[$name]);
  78  
  79          $this->routes[$name] = $route;
  80      }
  81  
  82      /**
  83       * Returns all routes in this collection.
  84       *
  85       * @return Route[] An array of routes
  86       */
  87      public function all()
  88      {
  89          return $this->routes;
  90      }
  91  
  92      /**
  93       * Gets a route by name.
  94       *
  95       * @param string $name The route name
  96       *
  97       * @return Route|null A Route instance or null when not found
  98       */
  99      public function get($name)
 100      {
 101          return isset($this->routes[$name]) ? $this->routes[$name] : null;
 102      }
 103  
 104      /**
 105       * Removes a route or an array of routes by name from the collection.
 106       *
 107       * @param string|string[] $name The route name or an array of route names
 108       */
 109      public function remove($name)
 110      {
 111          foreach ((array) $name as $n) {
 112              unset($this->routes[$n]);
 113          }
 114      }
 115  
 116      /**
 117       * Adds a route collection at the end of the current set by appending all
 118       * routes of the added collection.
 119       */
 120      public function addCollection(self $collection)
 121      {
 122          // we need to remove all routes with the same names first because just replacing them
 123          // would not place the new route at the end of the merged array
 124          foreach ($collection->all() as $name => $route) {
 125              unset($this->routes[$name]);
 126              $this->routes[$name] = $route;
 127          }
 128  
 129          $this->resources = array_merge($this->resources, $collection->getResources());
 130      }
 131  
 132      /**
 133       * Adds a prefix to the path of all child routes.
 134       *
 135       * @param string $prefix       An optional prefix to add before each pattern of the route collection
 136       * @param array  $defaults     An array of default values
 137       * @param array  $requirements An array of requirements
 138       */
 139      public function addPrefix($prefix, array $defaults = array(), array $requirements = array())
 140      {
 141          $prefix = trim(trim($prefix), '/');
 142  
 143          if ('' === $prefix) {
 144              return;
 145          }
 146  
 147          foreach ($this->routes as $route) {
 148              $route->setPath('/'.$prefix.$route->getPath());
 149              $route->addDefaults($defaults);
 150              $route->addRequirements($requirements);
 151          }
 152      }
 153  
 154      /**
 155       * Sets the host pattern on all routes.
 156       *
 157       * @param string $pattern      The pattern
 158       * @param array  $defaults     An array of default values
 159       * @param array  $requirements An array of requirements
 160       */
 161      public function setHost($pattern, array $defaults = array(), array $requirements = array())
 162      {
 163          foreach ($this->routes as $route) {
 164              $route->setHost($pattern);
 165              $route->addDefaults($defaults);
 166              $route->addRequirements($requirements);
 167          }
 168      }
 169  
 170      /**
 171       * Sets a condition on all routes.
 172       *
 173       * Existing conditions will be overridden.
 174       *
 175       * @param string $condition The condition
 176       */
 177      public function setCondition($condition)
 178      {
 179          foreach ($this->routes as $route) {
 180              $route->setCondition($condition);
 181          }
 182      }
 183  
 184      /**
 185       * Adds defaults to all routes.
 186       *
 187       * An existing default value under the same name in a route will be overridden.
 188       *
 189       * @param array $defaults An array of default values
 190       */
 191      public function addDefaults(array $defaults)
 192      {
 193          if ($defaults) {
 194              foreach ($this->routes as $route) {
 195                  $route->addDefaults($defaults);
 196              }
 197          }
 198      }
 199  
 200      /**
 201       * Adds requirements to all routes.
 202       *
 203       * An existing requirement under the same name in a route will be overridden.
 204       *
 205       * @param array $requirements An array of requirements
 206       */
 207      public function addRequirements(array $requirements)
 208      {
 209          if ($requirements) {
 210              foreach ($this->routes as $route) {
 211                  $route->addRequirements($requirements);
 212              }
 213          }
 214      }
 215  
 216      /**
 217       * Adds options to all routes.
 218       *
 219       * An existing option value under the same name in a route will be overridden.
 220       *
 221       * @param array $options An array of options
 222       */
 223      public function addOptions(array $options)
 224      {
 225          if ($options) {
 226              foreach ($this->routes as $route) {
 227                  $route->addOptions($options);
 228              }
 229          }
 230      }
 231  
 232      /**
 233       * Sets the schemes (e.g. 'https') all child routes are restricted to.
 234       *
 235       * @param string|string[] $schemes The scheme or an array of schemes
 236       */
 237      public function setSchemes($schemes)
 238      {
 239          foreach ($this->routes as $route) {
 240              $route->setSchemes($schemes);
 241          }
 242      }
 243  
 244      /**
 245       * Sets the HTTP methods (e.g. 'POST') all child routes are restricted to.
 246       *
 247       * @param string|string[] $methods The method or an array of methods
 248       */
 249      public function setMethods($methods)
 250      {
 251          foreach ($this->routes as $route) {
 252              $route->setMethods($methods);
 253          }
 254      }
 255  
 256      /**
 257       * Returns an array of resources loaded to build this collection.
 258       *
 259       * @return ResourceInterface[] An array of resources
 260       */
 261      public function getResources()
 262      {
 263          return array_unique($this->resources);
 264      }
 265  
 266      /**
 267       * Adds a resource for this collection.
 268       */
 269      public function addResource(ResourceInterface $resource)
 270      {
 271          $this->resources[] = $resource;
 272      }
 273  }