PHP Script Hooks - KL-Psychological-Methodology/ESMira GitHub Wiki

It is possible to extend an ESMira server's behavior at certain events (e.g., a participant uploading questionnaire data) via PHP scripts. This allows you to have your server perform additional actions without having to modify the server source code itself. Note that this is an advanced topic that requires both knowledge of the PHP programming language as well as access to your ESMira server's file system.

Extension Scripts

Certain api endpoint scripts will look for specific extension scripts in an extensions/ directory, and (if present) execute these after they are done running. This extensions/ directory needs to be located in the ESMira base directory (next to the directories api, backend, and so on). This directory does not exist by default but needs to be created by you (as well as the extension scripts). When doing so make sure that the permissions for accessing the directory (and scripts) are set correctly (e.g., it might be necessary to modify the user or group the directory belongs to, depending on the system ESMira runs on).

The relevant scripts will first execute fully and send their response to the client, ensuring that a slow or faulty extension script should not impact ESMira's normal functionality. Then, if the target extension script exists, it will be called from that api endpoint script. Therefore the extension script has access to the content of superglobals from the original request to the api endpoint (e.g., can access the questionnaire responses uploaded to datasets.php). This allows to e.g., react to specific data, or filter for data from specific studies. This could then for example be used to trigger a notification or email to researchers sent from a different server (functionality not included in ESMira itself).

The following sections describe the individual endpoint scripts that can be extended.

Dataset Uploads

datasets.php is called when a client uploads data from one or more events (such as questionnaire responses). The corresponding extension script is extensions/datasetExtension.php.

Message Upload

save_message.php is called when a client uploads a message a participant has sent. The corresponding extension script is extensions/messageExtension.php.

Merlin Log Upload

If you use the Merlin scripting language in your study and either generate a log programmatically, or if the script encounters an error, it will generate a Merlin log, which is sent to save_merlin_log.php. The corresponding extension script is extensions/merlinLogExtension.php.