Handling output

The output handler layer in this framework is pluggable. By default, it uses the widely- accepted JSON encoding type. This default is settable on a per-route basis. Using the simplistic 'hello world' example from above, you could make a small modification to alter the default output handler used by the /:name route by doing the following:

public $get = array('/:name' => array(
    'output_handler' => 'serialize',
    'function' => 'hello'
);

Notice that instead of the most basic 'route' => 'function_name' syntax, the value is changed to an array so that we can specify both the function to call and the default output handler to use for the endpoint. If the default output handler is invalid, and no other output handlers were specified during the query, an error will be thrown.

You can also override the default output handler by setting it before calling run() or listen():

\veneer\app::set_default('output_handler', 'serialize');
\veneer\app::run();

Also included out-of-the-box is the php 'serialize' type, and a plain text outputter. Originally, XML was also included, but due to the varying ways in which PHP can be compiled, and the fundamental differences between XML and other serializers, the built-in implementation has been removed in favor of simplicity.

You can invoke any API endpoint with any output handler by specifying it in the query parameters of the request, for instance:

$ curl -s http://localhost:8080/v1/hello/world?format=serialize
a:4:{s:8:"endpoint";s:5:"hello";s:7:"version";s:2:"v1";s:4:"status";i:200;s:8:"response";s:13:"Hello, world!";}
$ curl -s http://localhost:8080/v1/hello/world?format=plain
Hello, world!

Don't like using the query parameter "format"? No problem! You can change the default parameter name which indicates the output mechanism, and you can also specify it on a per- route basis. In best practice, you would never use a different query parameter in different API endpoints to specify the output handler, but veneer does not prevent you from doing that.

The following will change the default parameter name to "output_type":

\veneer\app::set_default('output_handler_param', 'output_type');
\veneer\app::run();

You can specify the same inside of your route definitions.

You can also pass output types using an HTTP header by the same name of your output handler parameter, like this:

$ curl -s -H 'format: json' http://localhost:8080

With these two different methods of specifying an output handler, internally veneer will use the following priority to determine how to send output back to you:

• An HTTP header by the same name of the route's handler parameter (default: format)
• The output handler parameter for the route (default: format)
• The default output handler for the route (default: json)
• text/plain, an error message, and a 415 Unsupported Media Type response.

There are constraints around output handlers, specifically what types of data can be handled. There are 2 main types that any outputter might support: string and array. Any handler that can handle array and string data would satisfy both of these. However, there might be some output handlers that cannot (for whatever reason) handle one or the other. An example is the plain outputter - it can handle dumping a raw string or integer, but it does not know how to dump an array in raw format. These constraints are settable on a per-handler basis within the handler class by implementing the appropriate interfaces, \veneer\output\str for string handlers, and \veneer\output\arr for array handlers. As an example, the json outputter would look something like the following:

namespace veneer\output\handler;
class json implements
    \veneer\output\arr,
    \veneer\output\str
{
    ...