[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Router Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Router;
  10  
  11  /**
  12   * A path router.
  13   *
  14   * @since  1.0
  15   */
  16  class Router implements RouterInterface, \Serializable
  17  {
  18      /**
  19       * An array of Route objects defining the supported paths.
  20       *
  21       * @var    Route[]
  22       * @since  2.0.0
  23       */
  24      protected $routes = [];
  25  
  26      /**
  27       * Constructor.
  28       *
  29       * @param   Route[]|array[]  $routes  A list of route maps or Route objects to add to the router.
  30       *
  31       * @since   1.0
  32       */
  33  	public function __construct(array $routes = [])
  34      {
  35          if (!empty($routes))
  36          {
  37              $this->addRoutes($routes);
  38          }
  39      }
  40  
  41      /**
  42       * Add a route to the router.
  43       *
  44       * @param   Route  $route  The route definition
  45       *
  46       * @return  $this
  47       *
  48       * @since   2.0.0
  49       */
  50  	public function addRoute(Route $route): RouterInterface
  51      {
  52          $this->routes[] = $route;
  53  
  54          return $this;
  55      }
  56  
  57      /**
  58       * Add an array of route maps or objects to the router.
  59       *
  60       * @param   Route[]|array[]  $routes  A list of route maps or Route objects to add to the router.
  61       *
  62       * @return  $this
  63       *
  64       * @since   2.0.0
  65       * @throws  \UnexpectedValueException  If missing the `pattern` or `controller` keys from the mapping array.
  66       */
  67  	public function addRoutes(array $routes): RouterInterface
  68      {
  69          foreach ($routes as $route)
  70          {
  71              if ($route instanceof Route)
  72              {
  73                  $this->addRoute($route);
  74              }
  75              else
  76              {
  77                  // Ensure a `pattern` key exists
  78                  if (! array_key_exists('pattern', $route))
  79                  {
  80                      throw new \UnexpectedValueException('Route map must contain a pattern variable.');
  81                  }
  82  
  83                  // Ensure a `controller` key exists
  84                  if (! array_key_exists('controller', $route))
  85                  {
  86                      throw new \UnexpectedValueException('Route map must contain a controller variable.');
  87                  }
  88  
  89                  // If defaults, rules have been specified, add them as well.
  90                  $defaults = $route['defaults'] ?? [];
  91                  $rules    = $route['rules'] ?? [];
  92                  $methods  = $route['methods'] ?? ['GET'];
  93  
  94                  $this->addRoute(new Route($methods, $route['pattern'], $route['controller'], $rules, $defaults));
  95              }
  96          }
  97  
  98          return $this;
  99      }
 100  
 101      /**
 102       * Get the routes registered with this router.
 103       *
 104       * @return  Route[]
 105       *
 106       * @since   2.0.0
 107       */
 108  	public function getRoutes(): array
 109      {
 110          return $this->routes;
 111      }
 112  
 113      /**
 114       * Parse the given route and return the information about the route, including the controller assigned to the route.
 115       *
 116       * @param   string  $route   The route string for which to find and execute a controller.
 117       * @param   string  $method  Request method to match, should be a valid HTTP request method.
 118       *
 119       * @return  ResolvedRoute
 120       *
 121       * @since   1.0
 122       * @throws  Exception\MethodNotAllowedException if the route was found but does not support the request method
 123       * @throws  Exception\RouteNotFoundException if the route was not found
 124       */
 125  	public function parseRoute($route, $method = 'GET')
 126      {
 127          $method = strtoupper($method);
 128  
 129          // Get the path from the route and remove and leading or trailing slash.
 130          $route = trim(parse_url($route, PHP_URL_PATH), ' /');
 131  
 132          // Iterate through all of the known routes looking for a match.
 133          foreach ($this->routes as $rule)
 134          {
 135              if (preg_match($rule->getRegex(), $route, $matches))
 136              {
 137                  // Check if the route supports this method
 138                  if (!empty($rule->getMethods()) && !\in_array($method, $rule->getMethods()))
 139                  {
 140                      throw new Exception\MethodNotAllowedException(
 141                          array_unique($rule->getMethods()),
 142                          sprintf('Route `%s` does not support `%s` requests.', $route, strtoupper($method)),
 143                          405
 144                      );
 145                  }
 146  
 147                  // If we have gotten this far then we have a positive match.
 148                  $vars = $rule->getDefaults();
 149  
 150                  foreach ($rule->getRouteVariables() as $i => $var)
 151                  {
 152                      $vars[$var] = $matches[$i + 1];
 153                  }
 154  
 155                  return new ResolvedRoute($rule->getController(), $vars, $route);
 156              }
 157          }
 158  
 159          throw new Exception\RouteNotFoundException(sprintf('Unable to handle request for route `%s`.', $route), 404);
 160      }
 161  
 162      /**
 163       * Add a GET route to the router.
 164       *
 165       * @param   string  $pattern     The route pattern to use for matching.
 166       * @param   mixed   $controller  The controller to map to the given pattern.
 167       * @param   array   $rules       An array of regex rules keyed using the route variables.
 168       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 169       *
 170       * @return  $this
 171       *
 172       * @since   2.0.0
 173       */
 174  	public function get(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 175      {
 176          return $this->addRoute(new Route(['GET'], $pattern, $controller, $rules, $defaults));
 177      }
 178  
 179      /**
 180       * Add a POST route to the router.
 181       *
 182       * @param   string  $pattern     The route pattern to use for matching.
 183       * @param   mixed   $controller  The controller to map to the given pattern.
 184       * @param   array   $rules       An array of regex rules keyed using the route variables.
 185       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 186       *
 187       * @return  $this
 188       *
 189       * @since   2.0.0
 190       */
 191  	public function post(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 192      {
 193          return $this->addRoute(new Route(['POST'], $pattern, $controller, $rules, $defaults));
 194      }
 195  
 196      /**
 197       * Add a PUT route to the router.
 198       *
 199       * @param   string  $pattern     The route pattern to use for matching.
 200       * @param   mixed   $controller  The controller to map to the given pattern.
 201       * @param   array   $rules       An array of regex rules keyed using the route variables.
 202       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 203       *
 204       * @return  $this
 205       *
 206       * @since   2.0.0
 207       */
 208  	public function put(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 209      {
 210          return $this->addRoute(new Route(['PUT'], $pattern, $controller, $rules, $defaults));
 211      }
 212  
 213      /**
 214       * Add a DELETE route to the router.
 215       *
 216       * @param   string  $pattern     The route pattern to use for matching.
 217       * @param   mixed   $controller  The controller to map to the given pattern.
 218       * @param   array   $rules       An array of regex rules keyed using the route variables.
 219       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 220       *
 221       * @return  $this
 222       *
 223       * @since   2.0.0
 224       */
 225  	public function delete(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 226      {
 227          return $this->addRoute(new Route(['DELETE'], $pattern, $controller, $rules, $defaults));
 228      }
 229  
 230      /**
 231       * Add a HEAD route to the router.
 232       *
 233       * @param   string  $pattern     The route pattern to use for matching.
 234       * @param   mixed   $controller  The controller to map to the given pattern.
 235       * @param   array   $rules       An array of regex rules keyed using the route variables.
 236       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 237       *
 238       * @return  $this
 239       *
 240       * @since   2.0.0
 241       */
 242  	public function head(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 243      {
 244          return $this->addRoute(new Route(['HEAD'], $pattern, $controller, $rules, $defaults));
 245      }
 246  
 247      /**
 248       * Add a OPTIONS route to the router.
 249       *
 250       * @param   string  $pattern     The route pattern to use for matching.
 251       * @param   mixed   $controller  The controller to map to the given pattern.
 252       * @param   array   $rules       An array of regex rules keyed using the route variables.
 253       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 254       *
 255       * @return  $this
 256       *
 257       * @since   2.0.0
 258       */
 259  	public function options(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 260      {
 261          return $this->addRoute(new Route(['OPTIONS'], $pattern, $controller, $rules, $defaults));
 262      }
 263  
 264      /**
 265       * Add a TRACE route to the router.
 266       *
 267       * @param   string  $pattern     The route pattern to use for matching.
 268       * @param   mixed   $controller  The controller to map to the given pattern.
 269       * @param   array   $rules       An array of regex rules keyed using the route variables.
 270       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 271       *
 272       * @return  $this
 273       *
 274       * @since   2.0.0
 275       */
 276  	public function trace(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 277      {
 278          return $this->addRoute(new Route(['TRACE'], $pattern, $controller, $rules, $defaults));
 279      }
 280  
 281      /**
 282       * Add a PATCH route to the router.
 283       *
 284       * @param   string  $pattern     The route pattern to use for matching.
 285       * @param   mixed   $controller  The controller to map to the given pattern.
 286       * @param   array   $rules       An array of regex rules keyed using the route variables.
 287       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 288       *
 289       * @return  $this
 290       *
 291       * @since   2.0.0
 292       */
 293  	public function patch(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 294      {
 295          return $this->addRoute(new Route(['PATCH'], $pattern, $controller, $rules, $defaults));
 296      }
 297  
 298      /**
 299       * Add a route to the router that accepts all request methods.
 300       *
 301       * @param   string  $pattern     The route pattern to use for matching.
 302       * @param   mixed   $controller  The controller to map to the given pattern.
 303       * @param   array   $rules       An array of regex rules keyed using the route variables.
 304       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 305       *
 306       * @return  $this
 307       *
 308       * @since   2.0.0
 309       */
 310  	public function all(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface
 311      {
 312          return $this->addRoute(new Route([], $pattern, $controller, $rules, $defaults));
 313      }
 314  
 315      /**
 316       * Serialize the router.
 317       *
 318       * @return  string  The serialized router.
 319       *
 320       * @since   2.0.0
 321       */
 322  	public function serialize()
 323      {
 324          return serialize($this->__serialize());
 325      }
 326  
 327      /**
 328       * Serialize the router.
 329       *
 330       * @return  array  The data to be serialized
 331       *
 332       * @since   2.0.0
 333       */
 334  	public function __serialize()
 335      {
 336          return [
 337              'routes' => $this->routes,
 338          ];
 339      }
 340  
 341      /**
 342       * Unserialize the router.
 343       *
 344       * @param   string  $serialized  The serialized router.
 345       *
 346       * @return  void
 347       *
 348       * @since   2.0.0
 349       */
 350  	public function unserialize($serialized)
 351      {
 352          $this->__unserialize(unserialize($serialized));
 353      }
 354  
 355      /**
 356       * Unserialize the router.
 357       *
 358       * @param   array  $data  The serialized router.
 359       *
 360       * @return  void
 361       *
 362       * @since   2.0.0
 363       */
 364  	public function __unserialize(array $data)
 365      {
 366          $this->routes = $data['routes'];
 367      }
 368  }