robotpony/Presto — pull request #37 by robotpony (2013-02-23 00:58:44+00:00)
Title: 1.1 routing and test tool improvements

**Presto 1.1 alpha 1**

(Including @adam-patterson for review)

## Compatibility note

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

* `API` base startup has been simplified (Presto will throw an exception if 1.0 usage is detected)
* Delegate parameters to classes based on `API` now pass each useful part of `$ctx` is passed as an individual parameter *(see parameter passing below)*
* `add_delegate` has been removed (replaced by folder delegation)
* The `Request::URI` class has been removed (functionality was moved to `.htaccess` for more predictable routing

## Alpha 1 features

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

* Dispatching to folders of APIs
* 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:

* `add_filter` (repurposing `add_delegate` for parameter handling)

## 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 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"}