[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   * Interface defining a HTTP path router.
  13   *
  14   * @since  2.0.0
  15   */
  16  interface RouterInterface
  17  {
  18      /**
  19       * Add a route to the router.
  20       *
  21       * @param   Route  $route  The route definition
  22       *
  23       * @return  $this
  24       *
  25       * @since   2.0.0
  26       */
  27  	public function addRoute(Route $route): RouterInterface;
  28  
  29      /**
  30       * Add an array of route maps or objects to the router.
  31       *
  32       * @param   Route[]|array[]  $routes  A list of route maps or Route objects to add to the router.
  33       *
  34       * @return  $this
  35       *
  36       * @since   2.0.0
  37       * @throws  \UnexpectedValueException  If missing the `pattern` or `controller` keys from the mapping array.
  38       */
  39  	public function addRoutes(array $routes): RouterInterface;
  40  
  41      /**
  42       * Get the routes registered with this router.
  43       *
  44       * @return  Route[]
  45       *
  46       * @since   2.0.0
  47       */
  48  	public function getRoutes(): array;
  49  
  50      /**
  51       * Parse the given route and return the information about the route, including the controller assigned to the route.
  52       *
  53       * @param   string  $route   The route string for which to find and execute a controller.
  54       * @param   string  $method  Request method to match, should be a valid HTTP request method.
  55       *
  56       * @return  ResolvedRoute
  57       *
  58       * @since   2.0.0
  59       * @throws  Exception\MethodNotAllowedException if the route was found but does not support the request method
  60       * @throws  Exception\RouteNotFoundException if the route was not found
  61       */
  62  	public function parseRoute($route, $method = 'GET');
  63  
  64      /**
  65       * Add a GET route to the router.
  66       *
  67       * @param   string  $pattern     The route pattern to use for matching.
  68       * @param   mixed   $controller  The controller to map to the given pattern.
  69       * @param   array   $rules       An array of regex rules keyed using the route variables.
  70       * @param   array   $defaults    An array of default values that are used when the URL is matched.
  71       *
  72       * @return  $this
  73       *
  74       * @since   2.0.0
  75       */
  76  	public function get(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
  77  
  78      /**
  79       * Add a POST route to the router.
  80       *
  81       * @param   string  $pattern     The route pattern to use for matching.
  82       * @param   mixed   $controller  The controller to map to the given pattern.
  83       * @param   array   $rules       An array of regex rules keyed using the route variables.
  84       * @param   array   $defaults    An array of default values that are used when the URL is matched.
  85       *
  86       * @return  $this
  87       *
  88       * @since   2.0.0
  89       */
  90  	public function post(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
  91  
  92      /**
  93       * Add a PUT route to the router.
  94       *
  95       * @param   string  $pattern     The route pattern to use for matching.
  96       * @param   mixed   $controller  The controller to map to the given pattern.
  97       * @param   array   $rules       An array of regex rules keyed using the route variables.
  98       * @param   array   $defaults    An array of default values that are used when the URL is matched.
  99       *
 100       * @return  $this
 101       *
 102       * @since   2.0.0
 103       */
 104  	public function put(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 105  
 106      /**
 107       * Add a DELETE route to the router.
 108       *
 109       * @param   string  $pattern     The route pattern to use for matching.
 110       * @param   mixed   $controller  The controller to map to the given pattern.
 111       * @param   array   $rules       An array of regex rules keyed using the route variables.
 112       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 113       *
 114       * @return  $this
 115       *
 116       * @since   2.0.0
 117       */
 118  	public function delete(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 119  
 120      /**
 121       * Add a HEAD route to the router.
 122       *
 123       * @param   string  $pattern     The route pattern to use for matching.
 124       * @param   mixed   $controller  The controller to map to the given pattern.
 125       * @param   array   $rules       An array of regex rules keyed using the route variables.
 126       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 127       *
 128       * @return  $this
 129       *
 130       * @since   2.0.0
 131       */
 132  	public function head(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 133  
 134      /**
 135       * Add a OPTIONS route to the router.
 136       *
 137       * @param   string  $pattern     The route pattern to use for matching.
 138       * @param   mixed   $controller  The controller to map to the given pattern.
 139       * @param   array   $rules       An array of regex rules keyed using the route variables.
 140       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 141       *
 142       * @return  $this
 143       *
 144       * @since   2.0.0
 145       */
 146  	public function options(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 147  
 148      /**
 149       * Add a TRACE route to the router.
 150       *
 151       * @param   string  $pattern     The route pattern to use for matching.
 152       * @param   mixed   $controller  The controller to map to the given pattern.
 153       * @param   array   $rules       An array of regex rules keyed using the route variables.
 154       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 155       *
 156       * @return  $this
 157       *
 158       * @since   2.0.0
 159       */
 160  	public function trace(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 161  
 162      /**
 163       * Add a PATCH 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 patch(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 175  
 176      /**
 177       * Add a route to the router that accepts all request methods.
 178       *
 179       * @param   string  $pattern     The route pattern to use for matching.
 180       * @param   mixed   $controller  The controller to map to the given pattern.
 181       * @param   array   $rules       An array of regex rules keyed using the route variables.
 182       * @param   array   $defaults    An array of default values that are used when the URL is matched.
 183       *
 184       * @return  $this
 185       *
 186       * @since   2.0.0
 187       */
 188  	public function all(string $pattern, $controller, array $rules = [], array $defaults = []): RouterInterface;
 189  }