Stud.IP  4.0
 All Data Structures Namespaces Files Functions Variables Groups
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.

// 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_idthe ID of the consumer this router should associate to

Member Function Documentation

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

Describe one or more routes.

// 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_templateURI template to describe or pass an array to describe multiple routes.
String | null$descriptiondescription of the route
String$methodmethod 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$uriURI to dispatch (defaults to `$_SERVER['PATH_INFO']`)
String$methodRequest method (defaults to the method of the actual HTTP request or "GET")
Returns
Response a Response object containing status, headers and body
Exceptions
RouterExceptionmay 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$routethe matched route out of Router::matchRoute; an array with keys 'handler', 'conditions' and 'source'
array$parametersthe 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_idID 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$urithe 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$urithe URI to match
String$methodthe HTTP request method to match
DefaultRenderer$content_rendererthe 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$urithe 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_methodexpected HTTP request method
String$uri_templateexpected URI template, for example:
"/user/:user_id/events"
Array$handlerrequest 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_nobodyWhether the route can be accessed as nobody user (true) or not (false). Defaults to false.
Returns
Router returns itself to allow chaining
Exceptions
\Exceptionif passed HTTP request method is not supported
registerRenderer (   $renderer,
  $is_default = false 
)

Registers a content renderer.

Parameters
DefaultRenderer$rendererinstance 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->registerRoutes(new ExampleRouteMap());
Parameters
RouteMap$mapthe 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: