Public Member Functions
	register ($request_method, $uri_template, $handler, $conditions=[], $source= 'unknown', $allow_nobody=false)

	registerRoutes (RouteMap $map)

	describe ($uri_template, $description=null, $method= 'get')

	getRoutes ($describe=false, $check_access=true)

	dispatch ($uri=null, $method=null)

	registerRenderer ($renderer, $is_default=false)

	setupAuth ()

Static Public Member Functions
static	getInstance ($consumer_id=null)

static	getSupportedMethods ()

Protected Member Functions
	__construct ($consumer_id)

	execute ($route, $parameters)

	negotiateContent ($uri)

	matchRoute ($uri, $method, $content_renderer)

	getMethodsForUri ($uri)

Protected Attributes
	$user = null

	$routes = []

	$renderers = []

	$content_renderer = false

	$default_renderer = false

	$conditions = []

	$descriptions = []

	$consumers = []

	$permissions = false

Static Protected Attributes
static	$instances = []

static	$supported_methods

Detailed Description

Die Aufgabe des Routers ist das Anlegen und Auswerten eines Mappings von sogenannten Routen (Tupel aus HTTP-Methode und Pfad) auf Code.

Dazu werden zunÃ¤chst Routen mittels der Funktion Router::registerRoutes registriert.

Wenn dann ein HTTP-Request eingeht, kann mithilfe von Router::dispatch und HTTP-Methode bzw. Pfad der zugehÃ¶rige Code gefunden und ausgefÃ¼hrt werden. Der Router bildet aus dem RÃ¼ckgabewert des Codes ein Response-Objekt, das er als Ergebnis zurÃ¼ck meldet.

$router = Router::getInstance();
// register a sample Route
$router->registerRoutes(new ExampleRoute);
// dispatch to therein defined Routes
$response = $router->dispatch('/example', 'GET');
// render response
$response->output();

Author: Jan-Hendrik Willms tleil.nosp@m.ax+s.nosp@m.tudip.nosp@m.@gma.nosp@m.il.co.nosp@m.m; mlunz.nosp@m.ena@.nosp@m.uos.d.nosp@m.e GPL 2 or later

See Also: Inspired by http://blog.sosedoff.com/2009/07/04/simpe-php-url-routing-controller/

Since: Stud.IP 3.0

Constructor & Destructor Documentation

__construct ( $consumer_id )

protected

Constructs the router.

Parameters

mixed $consumer_id the ID of the consumer this router should associate to

Member Function Documentation

describe	(	$uri_template,
		$description = `null`,
		$method = `'get'`
	)

Describe one or more routes.

$router = \RESTAPI\Router::getInstance();
// describe a single route
$router->describe('/foo', 'returns everything about foo', 'get');
// describe several routes that use the same path
$router->describe('/foo', array(
    'get'    => 'returns everything about foo',
    'put'    => 'updates all of foo',
    'delete' => 'empty up foo'
));
// describe several routes
$router->describe(array(
    '/foo' => array(
                  'get'    => 'returns everything about foo',
                  'put'    => 'updates all of foo',
                  'delete' => 'empty up foo'),
    '/bar' => array(...),
));

Parameters

String \| Array	$uri_template	URI template to describe or pass an array to describe multiple routes.
String \| null	$description	description of the route
String	$method	method to describe.

Returns: Router returns instance of itself to allow chaining

dispatch	(	$uri = `null`,
		$method = `null`
	)

Dispatches an URI across the defined routes and produces a Response object which may then be send back (using #output).

Parameters

mixed	$uri	URI to dispatch (defaults to `$_SERVER['PATH_INFO']`)
String	$method	Request method (defaults to the method of the actual HTTP request or "GET")

Returns: Response a Response object containing status, headers and body

Exceptions

RouterException may throw such an exception if there is no matching route (404) or if there is one, but the consumer is not authorized to it (403)

execute	(	$route,
		$parameters
	)

protected

Takes a route and the parameters out of the requested path and executes the handler of the route.

Parameters

array	$route	the matched route out of Router::matchRoute; an array with keys 'handler', 'conditions' and 'source'
array	$parameters	the matched parameters out of Router::matchRoute; something like: `array('user_id' => '23a21d...e78f')`

Returns: Response the resulting Response object which is then polished in Router::dispatch

static getInstance ( $consumer_id = null )

static

Returns (and if neccessary, initializes) a (cached) router object for an optional consumer id.

Parameters

mixed $consumer_id ID of the consumer (defaults to 'global')

Returns: Router returns the Router instance associated to the consumer ID (or to the 'global' ID)

getMethodsForUri ( $uri )

protected

Returns all methods the given uri responds to.

Parameters

String $uri the URI to match

Returns: array of all of responding methods

getRoutes	(	$describe = `false`,
		$check_access = `true`
	)

Get list of registered routes - optionally with their descriptions.

Parameters

bool	$describe	(optional) include descriptions, defaults to `false`
bool	$check_access	(optional) only show methods this router's consumer is authorized to, defaults to `true`

Returns: array list of registered routes

static getSupportedMethods ( )

static

Returns a list of all supported methods.

Returns: array of methods as strings

matchRoute	(	$uri,
		$method,
		$content_renderer
	)

protected

Tries to match a route given a URI and a HTTP request method.

Parameters

String	$uri	the URI to match
String	$method	the HTTP request method to match
DefaultRenderer	$content_renderer	the used ContentRenderer which is needed to remove a file extension

Returns: array an array containing the matched route and the found parameters

negotiateContent ( $uri )

protected

Negotiate content using the registered content renderers. The first ContentRenderer that returns true when calling ContentRenderer::shouldRespondTo gets the job.

Parameters

String $uri the URI to which the content renderers may respond

Returns: ContentRenderer either a ContentRenderer that responds to the URI or the default ContentRenderer of this router.

register	(	$request_method,
		$uri_template,
		$handler,
		$conditions = `[]`,
		$source = `'unknown'`,
		$allow_nobody = `false`
	)

Registers a handler for a specific combination of request method and uri template.

Parameters

String	$request_method	expected HTTP request method
String	$uri_template	expected URI template, for example: "/user/:user_id/events"
Array	$handler	request handler array: array($object, "methodName")
Array	$conditions	(optional) an associative array using the name of parameters as keys and regexps as value
string	$source	(optional) this denotes the origin of a route. Usually either 'core' or 'plugin', but defaults to 'unknown'.
bool	$allow_nobody	Whether the route can be accessed as nobody user (true) or not (false). Defaults to false.

Returns: Router returns itself to allow chaining

Exceptions

\Exception if passed HTTP request method is not supported

registerRenderer	(	$renderer,
		$is_default = `false`
	)

Registers a content renderer.

Parameters

DefaultRenderer	$renderer	instance of a content renderer
boolean	$is_default	(optional) set this renderer as default?; defaults to `false`

Returns: Router returns itself to allow chaining

registerRoutes ( RouteMap $map )

Registers the routes defined in a RouteMap instance using docblock annotations (like ) of its methods.

$router = \RESTAPI\Router::getInstance();
$router->registerRoutes(new ExampleRouteMap());

Parameters

RouteMap $map the RouteMap instance to register

Returns: Router returns itself to allow chaining

setupAuth ( )

Sets up the authentication for the router.

Field Documentation

$conditions = []

protected

$consumers = []

protected

$content_renderer = false

protected

$default_renderer = false

protected

$descriptions = []

protected

$instances = []

staticprotected

$permissions = false

protected

$renderers = []

protected

$routes = []

protected

$supported_methods

staticprotected

Initial value:

= [
        'get', 'post', 'put', 'delete', 'patch', 'options', 'head'
    ]

$user = null

protected

Holds the user object of the user that is accessing the API. This is null for nobody users.

The documentation for this class was generated from the following file:

lib/classes/restapi/Router.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation