f3-rest

Lightweight and easy to use Fatfree based REST api handler.

Usage

with composer:

composer require rigil/f3-rest

Then you create your api classes derived from \Rest\Controller:

hello.php

class Hello extends \Rest\Controller {
 function get($f3, $params) {
 $this->success([
 'headers' => $this->headers, // lowercase version of $f3->get('HEADERS')
 'params' => $params,
 'get' => $f3->GET,
 ]);
 }
 function post($f3, $params) {
 if (!$f3->BODY) return $this->error(400, 'empty body');
 $this->success([
 'headers' => $this->headers,
 'params' => $params,
 'get' => $f3->GET,
 'post' => $f3->POST,
 'body' => $this->format->from($f3->BODY),
 ]);
 }
 function put($f3, $params) {
 $this->post($f3, $params);
 }
}

index.php

require("vendor/autoload.php");
$f3 = \Base::instance();
$f3->set('AUTOLOAD', './');
$f3->set('ONERROR', function($f3){\Rest\Error::onError($f3);}); // recommanded
$f3->map('/api/@endpoint', 'Hello');
$f3->map('/api/@endpoint/@id', 'Hello');
$f3->run();

See also the example directory.

Rest\Controller class

It's an abstract class meant to be derived for your api endpoints.

On construction, it loads the defined formatters for input/output (see formatters), selecting a compatible one from the Content-Type header if it exists. It also calls the init() method that you can override in your class to do additional stuff.

If no function is defined in the ONERROR fatfree variable, it defines it to its own Rest\Error::onError() static function, which uses the selected formatter to generate the error response.

Then it provides 2 helper methods to reply a success or error of the request.

init()

class MyEndpoint extends \Rest\Controller {
 function init($f3, $params) {
 // $f3 and $params have the same meaning than in routed methods
 }
}

success()

function success($data = null, $code = 200)

$data is the variable that will be passed to the formatter to generate the response body. $code is available if you want to send other HTTP status than 200 (201 on creation for example).

error()

function error($code = 500, $text = '')

$code is the HTTP status returned, and $text an optional error message. See error handler for more information.

Formatters

The library has a powerfull, yet simple and extensible format handling, based on the Rest\Format class, usable from the Controller with the protected $format property (as showed in the usage example).

By default, 2 formatters are available:

• text: does no transformation at all
• json: decode/encode json data

json is the default used formatter if no default is set.

Declaring formatters

They are set in a custom formats section of the fatfree hive/configuration. By default (if no formatter is declared), the library automatically adds its default ones and uses json by default:

[formats]
json = \Rest\Formats\Json => application/json
text = \Rest\Formats\Text => plain/text

The format is as follow:

• the key is the formatting code that can be used when setting the DEFAULT_FORMAT variable
• the value is divided in 2 parts (like in array key/value):
  • first is the handling class (see below for a formatting class definition)
  • next is a comma separated list of mime types that will be managed by this formatter (for example: text/xml,application/xml) : the Format will use it to determine the right formatter from the Content-Type header on request, and setting the right one on response.

Note that explicitely declaring at least one formatter in formats hive automatically prevents from loading default ones (then json and text wont be loaded anymore, unless their are explicitely added).

Setting default formatter

Set DEFAULT_FORMAT variable in your fatfree config:

\Base::instance()->set('DEFAULT_FORMAT', 'text');

The Format class

Create a new formatter

You can easily extend available formatters with simple classes providing 2 static functions:

from()

static function from($src, $options)

Is used to convert text input (request body) to the desired type (usually an array).

The $options argument is forwarded from Format::from().

to()

static function to($src, $options)

Is used to convert input (usually an array) to a text (response body).

The $options argument is forwarded from Format::to()

Error handler