Public Member Functions | |
| __construct () | |
| init ($router, $route) | |
| paginated ($data, $total, $uri_params=[], $query_params=[]) | |
| paginate ($uri_format, $total, $offset=null, $limit=null) | |
| collect ($data) | |
| status ($status) | |
| headers ($headers=[]) | |
| body ($body) | |
| contentType ($mime_type, $params=[]) | |
| error ($status, $body=null) | |
| etag ($value, $strong_etag=true, $new_resource=null) | |
| expires ($amount, $cache_control=[]) | |
| cacheControl ($values) | |
| halt () | |
| lastModified ($time) | |
| notFound ($body=null) | |
| redirect ($url, $args=null) | |
| sendFile ($_path, $opts=[]) | |
| url ($addr, $url_params=null) | |
| urlf ($addr_f, $format_params, $url_params=null) | |
| getRoutes ($http_method=null) | |
| getResponse () | |
Protected Member Functions | |
| extractConditions ($docblock, $conditions=[]) | |
Protected Attributes | |
| $router | |
| $route | |
| $data = null | |
| $response | |
| $pagination = false | |
| $offset | |
| $limit | |
Detailed Description
RouteMaps define and group routes to resources.
Instances of RouteMaps are registered with the RESTAPI to participate in the routing business.
A RouteMap defines at least one handler method which has to be annotated with one of these annotations correlating to HTTP request methods:
By default, all API routes are unaccessible for nobody users. To explicitly allow access for nobody users, add the allow_nobody tag to the handler method's doc block. Example:
As soon as the Router matches a HTTP request to a handler defined in a RouteMap, it calls RouteMap::init to initialize it and especially the instance field $this->response of type RESTAPI. You do not call RouteMap::init on your own.
After the router has initialized this RouteMap, the router tries to call a method before of this signature:
The parameter $handler is a callable (as in function is_callable) consisting of the instance of this RouteMap and the name of a method of this instance. You may change the values of this array to redirect to another handler.
The parameter $parameters is an associative array whose keys correlate to the placeholders in the matched URI template. The values are the actual values of that placeholders in regard to the HTTP request.
After calling RouteMap::before control is transfered to the actual handler method. The values of the placeholders in the URI template of the annotation are send as arguments to the handler.
Example: We have got this handler method defined:
The router receives a request like this: http://[..]/foo/1/bar/2 and matches it to our fooHandler which is then called something like that:
In your handler methods you have to process the input and return some output data, which is then rendered in an appropriate way after negotiating the content format in the Router.
Thus the return value of your handler method becomes the body of the HTTP response.
The RouteMap class defines several methods to ease up your work with the HTTP specifica.
The methods RouteMap::status, RouteMap::headers and RouteMap::body correlate to the components of a HTTP response.
There are helpers for returning paginated collections, see RouteMap::paginated.
If you encounter an error or have to stop further processing, see methods RouteMap::halt, RouteMap::error and RouteMap::notFound.
These methods are DISRUPTIVE as they immediately stop the control flow in your handler:
If you want to simply send a redirection response (HTTP status code of 302 or 303), you may find calling RouteMap::redirect helpful.
To generate a URL to a handler, use RouteMap::url
When you find the need to return the content of a file, please see RouteMap::sendFile which will help you with streaming it to the client. For custom streaming just return a Closure from your handler method.
There are several other methods which you may find useful each matching a HTTP header:
- RouteMap::contentType
- RouteMap::etag
- RouteMap::expires
- RouteMap::cacheControl
- RouteMap::lastModified
You can access the data sent in the body of the current HTTP request using the $this->data instance variable.
- If the request was of Content-Type
application/json, the body of the request is decoded usingjson_decode. - If the request was of Content-Type
application/x-www-form-urlencoded, the body of the request is decoded usingparse_str. - Otherwise the request will not be parsed and
$this->datawill just contain the raw string.
NOTE: The result of the described parsing will always contain strings encoded in windows-1252. If the original body was UTF-8 encoded, it is automatically re-encoded to windows-1252.
- Since
- Stud.IP 3.0
Constructor & Destructor Documentation
◆ __construct()
| __construct | ( | ) |
Constructor of the route map. Initializes neccessary offset and limit parameters for pagination.
Member Function Documentation
◆ body()
| body | ( | $body | ) |
Set the HTTP body of the current response.
- Parameters
-
string $body the body to send back
◆ cacheControl()
| cacheControl | ( | $values | ) |
This sets the Cache-Control header of the HTTP response.
Example:
- Parameters
-
array $values an array containing Cache-Control directives.
◆ collect()
| collect | ( | $data | ) |
Low level method for paginating collections. You better use RouteMap::paginated instead of this.
Adjusts the result set to return a collection. A collection consists of the passed data array and the associated pagination information if available.
Be aware that the passed data has to be already sliced according to the pagination information.
- Parameters
-
array $data Actual dataset
- Returns
- array Collection "object"
◆ contentType()
| contentType | ( | $mime_type, | |
$params = [] |
|||
| ) |
Set the Content-Type of the HTTP response given a mime type and optionally further parameters as discusses in RFC 2616 14.17.
If no charset is given, it defaults to Stud.IP's 'windows-1252'.
Examples:
- Parameters
-
string $mime_type a string describing a MIME type like 'application/json' array $params optional parameters as described above
◆ error()
| error | ( | $status, | |
$body = null |
|||
| ) |
(Nice) sugar for calling RouteMap::halt and therefore as DISRUPTIVE. Code after calling RouteMap::error will not be evaluated.
- See also
- RouteMap::halt
- Parameters
-
integer $status a number indicating the HTTP status code; probably something 4xx or 5xx-ish string $body optional; the body of the HTTP response
◆ etag()
| etag | ( | $value, | |
$strong_etag = true, |
|||
$new_resource = null |
|||
| ) |
Sets the HTTP response's Etag header and halts, if the incoming HTTP request was a matching conditional GET using an 'If-None-Match' header. Thus it is a possibly DISRUPTIVE method as it will stop evaluation in that case and send a '304 Not Modified'.
Detail: If the request contains an If-Match or If-None-Match header set to *, a RouteMap assumes a match on safe (e.g. GET) and idempotent (e.g. PUT) requests. (In those cases it thinks that the resource already exists and therefore matches a wildcard.). This can be changed by passing an appropriate value for the $new_resource parameter.
Details of this can be found in RFC 2616 14.24 and 14.26
- Parameters
-
string $value an identifier uniquely identifying the current state of a resource bool $strong_etag optional; indicates whether the etag is a weak or strong (which is the default) cache validator. Have a look at the RFC for details. bool $new_resource optional; a way to tell the RouteMap that this is a new or existing resource. See above.
◆ expires()
| expires | ( | $amount, | |
$cache_control = [] |
|||
| ) |
This sets the Expires header and the Cache-Control directive max-age.
Amount is an integer number of seconds in the future indicating when the response should be considered "stale". The $cache_control parameter is passed to RouteMap::cacheControl along with the automatically generated max_age directive.
- Parameters
-
int $amount an integer specifying the number of seconds this resource will go stale. array $cache_control optional; more directives for RouteMap::cacheControl which is always automatically called using the computed max_age
◆ extractConditions()
|
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
◆ getResponse()
| getResponse | ( | ) |
Returns the response object
- Returns
- Response
◆ getRoutes()
| getRoutes | ( | $http_method = null | ) |
Returns a list of all the routes this routemap provides.
- Parameters
-
string $http_method Return only the routes for this specific http method (optional)
- Returns
- array of all routes grouped by method
◆ halt()
| halt | ( | ) |
This very important method stops further execution of your code. You may specify a status code, headers and the body of the resulting response. As the name implies, this method is DISRUPTIVE and will not return.
This method is called by every single DISRUPTIVE method.
- Parameters
-
integer $status optional; the response's status code array $headers optional; (additional) header lines which get merged with already set headers string $body optional; the response's body
◆ headers()
| headers | ( | $headers = [] | ) |
Set multiple response headers of the current response by merging them with already set ones.
- Parameters
-
array $headers the headers to set
- Returns
- array the headers of the current response
◆ init()
| init | ( | $router, | |
| $route | |||
| ) |
Initializes the route map by binding it to a router and passing in the current route.
- Parameters
-
Router $router Router to bind this route map to array $route The matched route out of Router::matchRoute; an array with keys 'handler', 'conditions' and 'source'
◆ lastModified()
| lastModified | ( | $time | ) |
This method sets the Last-Modified header of the HTTP response and halts on matching conditional GET requests. Thus this method is DISRUPTIVE in certain circumstances.
You have to give an integer typed timestamp (in seconds since epoch) to specify the data of the last modification to the requested resource.
If the current HTTP request contains an If-Modified-Since header, its value is compared to the specified $time parameter. Unless the header's value is sooner than the given $time, further execution is precluded and the RouteMap returns with a '304 Not Modified'.
- Parameters
-
integer $time a timestamp described in seconds since epoch
◆ notFound()
| notFound | ( | $body = null | ) |
Halts execution and returns a '404 Not Found' response.
Sugar for calling RouteMap::error(404) and therefore DISRUPTIVE. Code after calling RouteMap::notFound will not be evaluated.
- See also
- RouteMap::error
- RouteMap::halt
- Parameters
-
string $body optional; the body of the HTTP response
◆ paginate()
| paginate | ( | $uri_format, | |
| $total, | |||
$offset = null, |
|||
$limit = null |
|||
| ) |
Low level method for paginating collections. You better use RouteMap::paginated instead of this.
Set the pagination data used by the RouteMap::collect.
- Parameters
-
String $uri_format int $total mixed $offset mixed $limit
- Returns
- Routemap Returns instance of self to allow chaining
◆ paginated()
| paginated | ( | $data, | |
| $total, | |||
$uri_params = [], |
|||
$query_params = [] |
|||
| ) |
Marks this chunk of data as a slice of a larger data set with a sum of "total" entries.
- Parameters
-
mixed $data Chunk of data (should be sliced according to current offset and limit parameters). int $total The total number of data entries in the according set. array $uri_params Neccessary parameters when generating uris for the current route. array $query_params Optional query parameters.
◆ redirect()
| redirect | ( | $url, | |
$args = null |
|||
| ) |
Stops your code and redirects to the URL provided. This method is DISRUPTIVE like RouteMap::halt
In addition to the URL you may provide the status code, (additional) headers and a request body as you would when calling RouteMap::halt.
- See also
- RouteMap::halt
- Parameters
-
string $url the URL to redirect to; it will be filtered using RouteMap::url, so you may call it with those nice and small strings used in the annotations mixed $args optional; any combinations of the three parameters as in RouteMap::halt
◆ sendFile()
| sendFile | ( | $_path, | |
$opts = [] |
|||
| ) |
Stops execution of your code and starts sending the specified file. This method is DISRUPTIVE.
Using the $opts parameter you may specify the file's mime content type, sending an appropriate 'Content-Type' header, and you may specify the 'Content-Disposition' of the file transfer.
Example:
- Parameters
-
string $_path the filesystem path to the file to send array $opts optional; specify the content type, disposition and filename
◆ status()
| status | ( | $status | ) |
Set the HTTP status of the current response.
- Parameters
-
integer $status the HTTP status of the response
◆ url()
| url | ( | $addr, | |
$url_params = null |
|||
| ) |
Generate a URL to a given handler using a URL fragment and URL parameters.
Example:
- Parameters
-
string $addr a URL fragment to a handler array $url_params optional; URL parameters to add to the generated URL
- Returns
- string the resulting URL
◆ urlf()
| urlf | ( | $addr_f, | |
| $format_params, | |||
$url_params = null |
|||
| ) |
A vsprintf like variant to the RouteMap::url method.
Example:
- Parameters
-
string $addr_f a URL fragment to a handler containing sprintf-ish format sequences array $format_params values to fill into the format markers array $url_params optional; URL parameters to add to the generated URL
- Returns
- string the resulting URL
Field Documentation
◆ $data
|
protected |
◆ $limit
|
protected |
The limit of a RouteMap::paginated collection as requested by the client.
◆ $offset
|
protected |
The offset into a RouteMap::paginated collection as requested by the client.
◆ $pagination
|
protected |
Internal property which is used by RouteMap::paginated and contains everything about a paginated collection.
◆ $response
|
protected |
◆ $route
|
protected |
◆ $router
|
protected |
The documentation for this class was generated from the following file:
- lib/classes/restapi/RouteMap.php
