Installation

General requirements

The server-side implementation can be installed on any web server that supports PHP, version 7.4 or later, and common Apache HTTP functionality. Please note the following:

• The component does work with version 8.2, but has only been extensively tested with version 7.4.
• The eventsource resource requires that output buffering is turned off. In most server configurations this can be achieved with the directive "php_value output_buffering off" in a .htaccess file.
• Each eventsource session occupies one entry process. This is usually a limited resource in shared web hosting environments.
• The clientId generator requires that the PHP GMP library is enabled.
• The PHP socket extension must be enabled.

File locations

The items in the public directory must be made publicly accessible, typically by placing them inside the public_html folder.

The items in the private directory can be saved anywhere on the server as long as they can be accessed by the public PHP scripts. Directories for logging, sockets, and data require write access.

Boot scripts

In the default implementation, PHP constants required by CRSocket server resources are defined by public boot.php scripts. There is one top level script, located in the public crsocket directory, which defines constants used by all CRSocket resources and one, located at each app subdirectory, which defines app-specific constants. The current values defined at each level can be examined by means of boottest resources. In the project home page this includes:

• crsocket//boottest/
• crsocket/commtest/boottest/
• crsocket/mathtrials/boottest/

PHP constants

CRSocket server resources require several PHP constants. If the directory structure in the repository is kept unchanged, the only constant that needs to be modified is CRSOCKET_ROOT in the top level boot script. This constant must contain the path to the private crsocket directory.

Identifiers

APP_ID

Identifies a controller/responder pair. In the default implemtation, this is deduced from the basename of the directory where the resources related to the pair are located. This is used to ensure communication integrity and must correspond with the id transmitted by the client apps.

RESOURCE_NAME

The server resource that initiated the script, In the default implementation, this is deduced from the basename of the directory where the script is located. This id is used to create individual log files for each resource.

Source code directories

CRSOCKET_PHP

Path to the directory that contains shared CRSocket PHP scripts.

APP_PHP

Path to the directory that contains app specfic PHP scripts. The MathTrials app contains two such scripts: MathTrialsConfig.php which extends the CRConfig class with functionality related to authentication and saving, and MathTrial.php which contains info and response data from each trial.

Directories accessed by all CRSocket resources

CRSOCKET_DATA

Path to the directory that contains data files. In the default implementation this is used to save a single file named prevId.bin which contains the last generated clientId.

CRSOCKET_LOG

Path to the directory that contains log files. In the default implementation this is used to save files named [clientId].log contaning serialised crEvents transmitted by the corresponding clients where the logged attribute was set to true.

CRSOCKET_SOCK

Path to the directory that contains socket resources. This directory contains Unix sockets named [clientId].sock are used to transmit events between sendevent and eventsource scripts.

Directories accessed by app-specific resources

APP_LOG

Path to the directory that contains logs generated by app resources. There will be one log for each resource, e.g. sendevent.log and eventsource.log.

APP_DATA

Path to the directory that contains data collected by app resources. In the MathTrials app this directory is used to save trial results in a file named results.csv.