README

REST module for stonedz/pff2 (v4) to build JSON APIs with:

• automatic REST method dispatch (GET/POST/PUT/DELETE)
• optional auth hook per request
• API version prefix routing (e.g. api1/...)
• JSON exception output for API requests

Requirements

• PHP + stonedz/pff2 v4
• Module dependencies declared in this package:
  • exception_handler
  • pff2-permissions
• Optional module:
  • pff2-annotations (only needed for annotation-based REST detection)

Installation

composer require stonedz/pff2-rest

Enable modules in app config

In your app config.user.php, ensure the modules list includes:

$pffConfig['modules'] = [
	'exception_handler',
	'pff2-permissions',
	'pff2-rest',
];

If you want annotation-based REST detection, also add:

'pff2-annotations',

Module configuration

Create (or override) config at:

app/config/modules/pff2-rest/module.conf.yaml

Example:

moduleConf:
  annotationName: Rest
  enableAuth: true
  authType: token
  authClass: ApiAuthCkecker
  apiVersions:
	- api1

Config keys

• annotationName: method annotation name checked by pff2-annotations (when installed/enabled).
• enableAuth: if true, auth class is invoked before handling request.
• authType: currently informational in this module code.
• authClass: class name under namespace \pff\models\ implementing IRestAuth.
• apiVersions: URL prefixes treated as API version roots (api1, v2, etc).

How routing works

If request URL starts with a configured API version, pff2-rest rewrites route from:

/api1/users/42

to controller/action form:

Api1_Users/index/42

Then, if controller implements IRestController, action is replaced by HTTP method:

• GET → getHandler
• POST → postHandler
• PUT → putHandler
• DELETE → deleteHandler
• OPTIONS → immediate 200

If pff2-annotations is installed and enabled, methods marked with the configured annotation name are also treated as REST requests.

Creating a REST controller

Implement pff\modules\Iface\IRestController:

<?php

namespace pff\controllers;

use pff\Abs\AController;
use pff\modules\Iface\IRestController;

class Api1_Users_Controller extends AController implements IRestController
{
	public function getHandler()
	{
		echo json_encode(['ok' => true, 'method' => 'GET']);
	}

	public function postHandler()
	{
		echo json_encode(['ok' => true, 'method' => 'POST']);
	}

	public function putHandler()
	{
		echo json_encode(['ok' => true, 'method' => 'PUT']);
	}

	public function deleteHandler()
	{
		echo json_encode(['ok' => true, 'method' => 'DELETE']);
	}
}

Auth integration

When enableAuth: true, module creates:

\pff\models\<authClass>

and calls:

authorize(IController $controller)

So your auth model should implement pff\modules\Iface\IRestAuth.

Example:

<?php

namespace pff\models;

use pff\Iface\IController;
use pff\modules\Iface\IRestAuth;
use pff\modules\Exception\RestException;

class ApiAuthCkecker implements IRestAuth
{
	public function authorize(IController $controller)
	{
		$token = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
		if ($token === '') {
			throw new RestException('Unauthorized', 401);
		}
	}
}

Error output format

For REST requests, uncaught exceptions are rendered as JSON:

{
  "error": true,
  "message": "...",
  "file": "...::..."
}

HTTP status code is taken from exception code.

Notes

• The default sample value is ApiAuthCkecker (spelling from legacy config). Use any class name you want, as long as it exists under \pff\models\ and matches authClass.
• This module sets JSON output automatically for matched REST requests.
• For non-REST requests, normal pff2 flow is unchanged.