Router Class Reference

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()

__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()

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()

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()

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

getInstance()

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()

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()

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

getSupportedMethods()

static getSupportedMethods ( )

static

Returns a list of all supported methods.

Returns

array of methods as strings

matchRoute()

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()

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()

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

registerRenderer()

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()

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()

setupAuth

(

)

Sets up the authentication for the router.

Field Documentation

$conditions

$conditions = []

protected

$consumers

$consumers = []

protected

$content_renderer

$content_renderer = false

protected

$default_renderer

$default_renderer = false

protected

$descriptions

$descriptions = []

protected

$instances

$instances = []

staticprotected

$permissions

$permissions = false

protected

$renderers

$renderers = []

protected

$routes

$routes = []

protected

$supported_methods

$supported_methods

staticprotected

Initial value:

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

$user

$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