STAGES.md

Stages

Stages of handling a request in restler

When restler receives a request it handles it in the following stages:

1. get: Restler identifies request method, url, data and format
2. route: Finding out a matching route for the request
3. negotiate Applies content negotiation as requested by the api client.
4. preAuthFilter: If there is a filer applicable to the route before authentication it is applied.
5. Authenticate: If the selected route requires authentication it is applied.
6. postAuthFilter: If there is a filer applicable to the route after successful authentication it is applied.
7. validate: Applies validation for each and every parameter as defined through the phpdoc comments.
8. call: Finally calls the php method with the validated parameters.
9. message: Return value of the above call sent as the response in the selected format.

A successful request goes through all the above stages. Whereas a failed request runs until the stage of the failure and then returns a composed failure message taking the fail fast approach for improved performance.

We can subscribe to any of the following events to listen to them.

method	signature	description
onGet	onGet(Callable $function)	fired before reading the request details
onRoute	onRoute(Callable $function)	fired before finding the api method
onNegotiate	onNegotiate(Callable $function)	fired before content negotiation
onPreAuthFilter	onPreAuthFilter(Callable $function)	fired before pre auth filtering
onAuthenticate	onAuthenticate(Callable $function)	fired before auth
onPostAuthFilter	onPostAuthFilter(Callable $function)	fired before post auth filtering onValidate()
onValidate	onValidate(Callable $function)	fired before validation
onCall	onCall(Callable $function)	fired before api method call
onCompose	onCompose(Callable $function)	fired before composing response
onRespond	onRespond(Callable $function)	fired before sending response
onComplete	onComplete(Callable $function)	fired after sending response
onMessage	onMessage(Callable $function)	fired before composing error response

These methods are available both statically and dynamically at runtime. so both the following examples are valid.

Usage Examples:

1. Logging successful api responses

We can use onComplete method for logging.

require_once '../vendor/autoload.php';

use Luracast\Restler\Restler;
use Luracast\Restler\User;

$r = new Restler();

$r->onComplete(function () use ($r) {
    $log = array(
        'api'     =>json_encode($r->apiMethodInfo->parameters),
        'ip'      => User::getIpAddress(),
        'route'   => $r->apiMethodInfo->className.'::'.$r->apiMethodInfo->methodName,
        'method'  => $r->requestMethod,
        'parameters' => json_encode($r->apiMethodInfo->parameters)
    );
    print_r($log); //your logging function here!
});

$r->addAPIClass('Say');
$r->handle();

2. Lazily setting form style.

require_once '../vendor/autoload.php';

use Luracast\Restler\Restler;
use Luracast\Restler\UI\Forms;
use Luracast\Restler\UI\Foundation5Form;

//no dependency on restler instance so it can be called statically
Restler::onCall(function () { 
    Forms::setStyles(new Foundation5Form());
});

$r = new Restler();
$r->addAPIClass('Something');
$r->handle();