# 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();