robotpony/Presto — pull request #38 by bruce-alderson (2013-02-25 22:21:02+00:00)
Title: 1.1 alpha 2

**Presto 1.1 alpha 1**

*(Including @adam-patterson and @ngallagher87 for review)*

**Presto 1.1 breaks compatibility with 1.0 in a few important areas:**

* `API` base startup has been simplified, removing the class pre-scanning mechanism. Presto will throw an exception if 1.0 usage is detected.
* API parameters are flattened to their obvious parts (get parameters, options, put/post body, resource type). This deprecates the `$ctx` object, which is still available via `self::$call`.
* `add_delegate` has been removed, as it has been replaced by folder delegation
* `add_filter` has been removed (a candidate 1.1 feature), as the other features provided enough utility on their own
* `Request::URI` has been removed in favour of a simpler builder function. URI parsing is now spread over `htaccess` for more obvious routing rules.

## Alpha 1 features

This patch adds a number of features planned for 1.1, including:

* Dispatching to folders of APIs
* Preflighting dispatch calls for parameter and model processing
* Adds internal testing and debugging APIs (only available when enabled)
* Adds command line unit testing tools
* Adds a trace mode, and better exception logging
* Adds routing information to exceptions (if trace is enabled)

## Pending 1.1 changes:

* Install checklist updates (based on new internal APIs)
* Route tester / class generator tool (based on new internal APIs)

## Updated parameter passing

The calling convention for delegate API functions has changed from:

public function get($ctx) { }
public function get_article($ctx) { }
public function put_article($ctx) { }

To the more verbose form:

public function get($params, $options, $body, $type) { }
public function get_article($params, $options, $body, $type) { }
public function put_article($params, $options, $body, $type) { }

This makes the call parameters clearer than they were in the past.

## Example folder delegation

Folder delegation uses Apache rewriting to map folders of APIs to specific URLs. For example, Presto uses it for internal delegation to its `transmogrify` APIs:

RewriteRule ^(transmogrify/(?:info|system|tests))/(.*)\.(.*)$ /lib/delegator-index.php?r=$2&t=$3&c=$1 [L]

This routes all requests to 3 specific folders within `transmogrify` to files within the folders `info/`, `system/`, and `tests/` in `transmogrify/`.

Requests like:

get "transmogrify/system/httpd/headers/content-type.json"

Are mapped to:

transmogrify/system/httpd.php::httpd->get_headers();

## Example preflight delegation

API calls can be split into two parts to simplify handling complex model creation and parameter processing. The split adds a preflight call to a *model* function of the same root name as the API itself.

Consider a simple GET:

get "transmogrify/system/httpd/headers/content-type.json"

This call can optionally be split into the model creation and the API call itself.

The model creation preflight call would be:

http.php::http->get_headers_model($p = array('content-type')) {
return new Features($p);
}

The call receives the standard API request parameters, returning a newly created model object of some sort. This call can be used to check parameters, check preconditions, and massage parameters into useful/predictable values for the API call itself:

http.php::http->get_headers($featureModel) {
}

## Example routing trace

If `PRESTO_TRACE` is enabled, exceptions will include:

[OPTIONS] transmogrify/info/delegation.json #0 [OK]
{
"_presto_trace": {
"request": "/transmogrify/info/delegation.json",
"routing_scheme": {
"action": "options",
"class": "delegation",
"container": "transmogrify/info",
"file": "transmogrify/info/delegation.php",
"method": "options",
"options": [],
"params": [],
"resource": "",
"type": "json"
},
"version": "presto-v1.10"
},
"code": 404,
"message": "Can't find delegation->options"
}

The `_presto_trace` element is added to make debugging easier. This trace is also available in the error log (in trace mode only):

[Fri Feb 22 16:38:58 2013] [error] [client 127.0.0.1] PRESTO: _presto_trace, {"routing_scheme":{"container":"transmogrify\\/info","class":"delegation","file":"transmogrify\\/info\\/delegation.php","resource":"","type":"json","action":"get","method":"get","params":[],"options":[]},"request":"\\/transmogrify\\/info\\/delegation.json","version":"presto-v1.10"}