Request Handler Methods

This page describes how the request_foo() functions should behave with regards to input and output.

By standardizing on this, we can reuse the same methods for both the AJAX version and non-AJAX version of Lichen.

Basic Details

Request functions are stored in include/requests.inc.php. They are all prefixed with "request_", but otherwise follow the camelCase naming standard.

Function Details

Input

The request functions are not called with any parameters. It is expected that they fetch the required parameters out of the GET and POST variables directly. They are, after all, meant to be an interface between the passed variables and Lichen's internal handling functions.

This is still considered a bit of a hack and rather unneat.

To assist with getting request variables, a helper function has been defined.

_GETORPOST(key[, default]);

The function first checks $_GET for the key. If it exists, it is returned. Then, $_POST is checked for the key. If it does not exist there, the default value (if passed) is returned. The default value defaults to an empty string.

Processing

Request functions must not call die(). There is no reason to call die() in the middle of a function. die() is reserved for top level code, where the only possible correct action to perform is to exit. Basically, die(die()).

You also must not call remoteRequestSuccess() or remoteRequestFailure().

Output

The functions should return an associative array of data.

They must return the following key:

• success - boolean, TRUE if the request succeeded, or FALSE if it did not. If it is false, no other returned data is returned to the client (see below).

If you return False for success, you must also define two more keys:

• errorCode - a short, string error code that can cause the client to handle the error differently. For example, authentication failures return 'AUTH' for the errorCode, which allows the client to request the user to reattempt a login in case of a timeout.
• errorString - a string (translated) that describes the error condition. Make it friendly for the users, as it will be displayed to them.

If your request returns true, you can include any other data that was required to be returned by adding extra keys to the associative array that you return. For example, the message list returns keys called 'data', 'validityKey', and 'mailbox'. Whatever you return in your array is JSON encoded and sent to the client in an AJAX request, or utilised by the sequence handler in the case of a non-AJAX request.

Behaviour

Most request functions should not concern themselves with whether or not it is an AJAX request or not, although some requests, by their nature, are AJAX only.