Router Class Reference

Collaboration diagram for Router:

Public Member Functions
	register ($request_method, $uri_template, $handler, $conditions=array(), $source='unknown')
	registerRoutes (RouteMap $map)
	describe ($uri_template, $description=null, $method='get')
	getRoutes ($describe=false, $check_access=true)
	dispatch ($uri=null, $method=null, $request_body=null)
	registerRenderer ($renderer, $is_default=false)

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

Protected Member Functions
	__construct ($consumer_id)
	execute ($route, $parameters, $request_body=null)
	negotiateContent ($uri)
	matchRoute ($uri, $method, $content_renderer)
	getMethodsForUri ($uri)
	extractConditions ($docblock, $conditions=array())

Protected Attributes
	$supported_methods = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head']
	$routes = array()
	$renderers = array()
	$content_renderer = false
	$default_renderer = false
	$conditions = array()
	$descriptions = array()
	$consumers = array()
	$permissions = false

Static Protected Attributes
static	$instances = array()

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,
			$request_body = 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")
mixed	$request_body	Request body to use (optional, should be removed when Stud.IP requires PHP >= 5.6)

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)

Here is the call graph for this function:

execute()

execute (   $route,   $parameters,   $request_body = null  )

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')`
mixed	$request_body	Request body to use (optional, should be removed when Stud.IP requires PHP >= 5.6)

Returns

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

extractConditions()

extractConditions (   $docblock,   $conditions = array()  )

protected

Extracts defined conditions from a given docblock.

Parameters

DocBlock	$docblock	DocBlock to examine
Array	$conditions	Optional array of already defined conditions to extend

Returns

Array of all extracted conditions with the variable name as key and pattern to match as value

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)

Here is the caller graph for this function:

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

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
ContentRenderer	$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 = array(),
			$source = 'unknown'
	)

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'.

Returns

Router returns itself to allow chaining

Exceptions

Exception

if passed HTTP request method is not supported

registerRenderer()

registerRenderer	(		$renderer,
			$is_default = false
	)

Registers a content renderer.

Parameters

ContentRenderer	$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

Field Documentation

$conditions

$conditions = array()

protected

$consumers

$consumers = array()

protected

$content_renderer

$content_renderer = false

protected

$default_renderer

$default_renderer = false

protected

$descriptions

$descriptions = array()

protected

$instances

$instances = array()

staticprotected

$permissions

$permissions = false

protected

$renderers

$renderers = array()

protected

$routes

$routes = array()

protected

$supported_methods

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

protected

---

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

• lib/classes/restapi/Router.php