Update to latest

.gitignore

@@ -1,3 +1,4 @@
 # Ignore generated log files.
 /bin/*.log
-/bin/token.test
+/bin/token.test
+_config.php

.htaccess

@@ -0,0 +1,22 @@
+
+<IfModule mod_rewrite.c>
+
+RewriteEngine On
+RewriteBase /
+
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^(transmogrify/(?:info|system|tests))/(.*)\.(.*)$ /lib/delegator-index.php?r=$2&t=$3&c=$1 [L]
+RewriteRule ^(transmogrify/(?:info|system|tests))/$ /lib/delegator-index.php?r=$1&t=LIST [L]
+RewriteRule ^(transmogrify/.*)\.(.*)$ /lib/delegator-index.php?r=$1&t=$2 [L]
+RewriteRule ^(transmogrify/.*)$ /lib/delegator-index.php?r=$1&t=LIST [L]
+
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteRule ^(.*)$ /docs/index.php?presto&page=$1 [NC,QSA,L]
+</IfModule>
+
+
+ErrorDocument 404 /docs/index.php?presto&error=404
+ErrorDocument 500 /docs/index.php?presto&error=500
+ErrorDocument 401 /docs/index.php?presto&error=401
+ErrorDocument 403 /docs/index.php?presto&error=403

CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+# 1.1 - *Sim Sala Bim*
+
+**Presto 1.1 breaks compatibility with 1.0 in a few important areas:**
+
+* Adds subfolder delegation
+* Removes add_delegate*, URL, and other unused code (subfolder delegation is much simpler)
+* Improves debugging (PHP errors to error log, added trace mode)
+* Added unit tests
+* Updated setup tests (to use internal API)
+* `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)
+
+## 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"}
+
+
+# 1.0 - A la peanut butter sandwiches 
+
+* First public release
+* Adds sub delegates and param filtering
+
+# 0.8
+
+* Adds basic URI -> class/member delegation and auto data return by type

INSTALL.md

@@ -25,7 +25,7 @@ This file sets up Presto's delegator features, so that your classes are called i
 
 4. Copy the example API file and test:
 
-<pre>$ cp lib/presto/examples/info.php .
+<pre>$ cp lib/presto/setup-tests/info.php .
 $ curl [YOUR WEBROOT]/info.json	
 {"example":"This is some example information"}</pre>
 
@@ -41,4 +41,4 @@ The example API file writes a simple DOM (a `PHP` keyed array) as `JSON` back to
 
 You need to enable the JSON extension using a custom RC (not a custom .ini). Find the instructions here:
 
-* http://wiki.dreamhost.com/PHP.ini#Loading_PHP_5.3_extensions_on_all_domains_.28on_VPS_or_dedicated.29
+* http://wiki.dreamhost.com/PHP.ini#Loading_PHP_5.3_extensions_on_all_domains_.28on_VPS_or_dedicated.29

LICENSE.md

@@ -0,0 +1,12 @@
+# Free, free, share-alike
+
+Created by [Bruce Alderson](http://warpedvisions.org) (2011).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+**PS: use, extend, share, enjoy. Thanks!**

README.md

@@ -1,86 +1,81 @@
-Presto - PHP REST toolkit
-=========================
+# Presto 1.1 
 
-Presto is a small library for building simple, RESTful APIs using PHP. It's lightweight, decoupled, and focused on making web apps the right way; using APIs with clean URLs, which produce simple, clean output in standard formats like JSON, HTML, and XML.
+*Frugal PHP + REST toolkit*
 
-How is it different?
---------------------
+Presto is a library for building RESTful APIs in PHP `5.3+`. It's lightweight, decoupled, and focused on making web apps the right way; using APIs and clean URLs to produce output in standard formats like JSON, HTML, and XML.  It encourages separating views completely from your model and controller code, and to animate your user interfaces in HTML, CSS, and JavaScript. It also uses existing tools and libraries for what they're good at, like letting Apache deal with routing, and letting PHP load and execute a minimal amount of dynamic code.
 
-Presto has no views, no models, and no controllers[^1]. Instead it focuses on APIs built from simple classes. It encourages applications to be based on APIs, which feed web applications animated with HTML/CSS/JavaScript.
+## How is Presto different?
 
-A Presto API is simply a PHP class that maps to a resource or tree of resources. It has:
+Presto flattens standard MVC to fit REST requests better. It focuses on APIs built from simple classes, relying on the web server for routing and on PHP autoloading for delegating requests to class member calls. User interfaces are left to other toolkits, though Presto can serve up fragments of HTML with ease. Presto focuses on APIs.
 
-* Public members that map to requests (`GET thing/details.json` would map to `$thing->get_details()`)
-* Request parameters and input payloads that are packaged up and sanitized
-* Each route returns data as DOMs, which are automatically adapted to the requested `ContentType`
-* Errors are automatically converted into returned HTTP statuses
+### A quick example 
 
-The resulting code is focused on resources and the rules for those resources, and not boilerplate, excessive error checking, routing, and output generation.
+An API is a class with members named for each resource (or tree of resources). For example, an `apple` is a resource. You can request an `apple` over HTTP:
 
-[^1]: Note that Presto avoids MVC by solving a smaller problem and relying on built in functionality for delegation and generating output. 
+	GET fruit/apples/spartan.json?tags=large+red
 
-How it works
-------------
 
-Presto uses the best parts of PHP and Apache, as they're intended to be used. It relies on `.htaccess` for routing, and built-in PHP behaviours for delegation and class loading. The principle is that relying on existing, simple approaches results in less framework, fewer bugs, and less to learn that isn't useful elsewhere.
+Presto maps the request to a file, class, and class member automatically. It loads the file, creates an instance of the class, and executes the member that best fits:
 
-*Note: PHP 5.3 or better is requried, as Presto relies on anonymous functions, and other newer PHP features. This makes it possible to write very clean, simple web services.*
 
-An example API
---------------
-
-	class info 
-		extends API {
-
-		// Set up the API
-		public function __construct() {
-			parent::__construct(get_class());	
-			if (!self::isSignedIn()) throw new Exception('Auth required', 401);
-		}
-
-		// GET info/time.json - gets the local machine time
-		public function get_time($ctx) { 
-			$dom = (object) getdate();
-			return $dom; // <-- returns the DOM as JSON
+	/* Loaded from 'fruit/apples.php' */
+
+	class apples extends API {
+
+		public function get($params, $options, $body, $type) {
+
+			if (count($params) === 0)
+				throw new Exception('Missing required parameter', 400);
+
+			/* Exceptions are returned as valid HTTP/content type 
+					responses */
+
+			$thing = (object) array(
+				'name' => $params[0],
+				'tags' => $options['tags']
+			);
+
+			return $thing; // to client in requested format
 		}
-
-		// PUT info/time.json
-		public function put_time($ctx) { throw new Exception('Not implemented', 501); }
-		// POST info/time.json
-		public function post_time($ctx) { throw new Exception('Not implemented', 501); }
 	}
 
-The class promises a GET, PUT, and POST interface for time. All other requests will return a standard 404. The PUT and POST are not implemented yet, so they return a 501 (not implemented).
 
-Presto maps requests to PHP files and objects, providing parameters and other calling information in the `$ctx` parameter. A request like:
+The `$thing` is automatically converted by Presto to the requested `Content-Type`, either implied by the request or the appropriate HTTP header. For formats not supported by default, *Output Adapters* can be defined and registered, or the type can be passed through for resources that are not based DOM style data.
 
-	GET /info/time.json
-
-Maps to:
+Any HTTP request type is mapped automatically. For example, you can request a list of `apple` types available from the API:
 
-	[info.php] info->get_time($ctx);
-
-The context includes the call parameters, the `content-type`, and request method. Handling of `content-type` is built in for simple cases, so that any data returned from an API is automatically transformed into the required type. For our simple example, returning the result of `datetime()` to the request produces:
-
-	{
-		"seconds" => 40
-	    "minutes" => 58
-	    "hours"   => 21
-	    "mday"    => 17
-	    "wday"    => 2
-	    "mon"     => 6
-	    "year"    => 2003
-	    "yday"    => 167
-	    "weekday" => "Tuesday"
-	    "month"   => "June"
-	    "0"       => 1055901520
-	}
+	LIST apples.json?colour=red
+
+A LIST request is mapped to a function of the same name:
+
+	public function list(/* … */) { return array(); }
 
-Advanced features
------------------
 
-There are a number of ways you can extend Presto. You can:
+More complex resources are possible by either delegating (based on regex patterns), or by adding specific handlers. For example, you could add a `seeds` branch to the `apple` resource. Getting a list of seeds would map to:
+
+	public function list_seeds(/* … */) { array(); }
+
+### What about errors?
+
+Errors are handled by the toolkit as standard PHP exceptions and standard PHP errors are remapped (where possible) to exceptions to ensure that logic and code errors are returned to clients as valid API returns. This means that individual APIs do not need to check return values, nor do they need to `try` and `catch` unless they need to do something special. Presto maps the standard exceptions to HTTP statuses and output in whatever format was requested where possible.
+
+For example, if you encounter a parameter error you can simply throw an exception:
+
+	if (empty($param))
+		throw new Exception('Missing required parameter', 400);
+
+Presto translates the exception into a `400` with an appropriately encoded body.
+
+The resulting API code is much more focused on carefully testing parameters, retrieving appropriate resources, and building rich DOMs instead of boilerplate code, managing responses, excessive error checking, routing, and other complex output generation.
+
+
+Other interesting features
+==========================
+
+You can also:
 
 * Add additional `content-types` by adding *output adapters* (`JSON`, simple `XML`, and simple `HTML` are built in)
 * Add `content-type` filters to define what types of payloads a given resource supports.
 * Add *custom delegation* for special resource types
+
+**Note that PHP 5.3 or better is required, as Presto relies on anonymous functions and other newer PHP features. This makes it possible to write very clean, simple web services.**