HelPHP

Restresponse
in package

Tags
class

Restresponse

REST response handler for the REST server. This class manages REST API requests, including module/action routing, security checks, OID (Origin Identifier) management, and filesystem/network operations.

It automates module action calls, handles authentication, and provides utility methods for error handling and response formatting.

The main security measure is the requirement to be connected (OID/token). The OID is used to maintain the connection and authenticate the unique user.

It's working behind the api/index.php in your instance and with the help of libs/externals/Restserver.php as REST micro server.

see

api/index.php for instance usage.

see

tests/rest/ in your instance to find an api client for testing

Table of Contents

Properties

$data  : array<string|int, mixed>
$format  : string
$oid  : string|false

Methods

__construct()  : mixed
Decodes and checks request data, check the user agent and ip and route the command.
check_request_data()  : void
Checks and decodes the request data,
check_ua_and_ip()  : void
Make sure that user agent and client IP are correctly set in $this->data and $_SERVER.
checkOid()  : string|false
Checks and renews the OID, restoring the connection if valid.
command_route()  : void
Routes the command to the appropriate handler: - Hardcoded commands without OID - Hardcoded commands with OID - Module action (default)
error_on_file()  : string
Sets an error message in the response array based on the last filesystem error.
generateOid()  : string|false
Generates a new OID (Origin Identifier) token or updates an existing one.
missing_free_space()  : string
Sets a "missing free space" error message in the response array.
rest_commands()  : array<string|int, mixed>
Handles hardcoded REST commands that do not require OID (e.g., connection).
rest_commands_with_oid()  : array<string|int, mixed>
Handles hardcoded REST commands that require OID.
return_response()  : void
Formats and sets the response data, encrypting if needed.

Properties

$data

public array<string|int, mixed> $data

Decoded data (usually from JSON).

$oid

public string|false $oid

Communication token (Origin Identity).

Methods

__construct()

Decodes and checks request data, check the user agent and ip and route the command.

public __construct(string $module, string $action, mixed $params[, bool $no_crypt = false ]) : mixed
Parameters
$module : string

The module name.

$action : string

The action to perform.

$params : mixed

The parameters (raw or JSON/encrypted).

$no_crypt : bool = false

If true, do not decrypt data.

check_request_data()

Checks and decodes the request data,

public check_request_data() : void

sets $this->data, $this->oid, and $this->id.

Tags
throws
Exception

If required parameters are missing.

check_ua_and_ip()

Make sure that user agent and client IP are correctly set in $this->data and $_SERVER.

public check_ua_and_ip() : void

Helps maintain connection in difficult network configurations.

checkOid()

Checks and renews the OID, restoring the connection if valid.

public checkOid(string $oid) : string|false

Loads user data to update the token if needed.

Parameters
$oid : string

The OID token to check.

Tags
throws
Exception

If OID is unknown or invalid.

Return values
string|false —

The (possibly renewed) OID token, or false on error.

command_route()

Routes the command to the appropriate handler: - Hardcoded commands without OID - Hardcoded commands with OID - Module action (default)

public command_route() : void
Tags
throws
Exception

400 If OID is missing or command/module is unknown.

error_on_file()

Sets an error message in the response array based on the last filesystem error.

public error_on_file(array<string|int, mixed> &$return) : string
Parameters
$return : array<string|int, mixed>

The response array (by reference).

Return values
string —

in $return['message'] (the error message)

generateOid()

Generates a new OID (Origin Identifier) token or updates an existing one.

public generateOid([array<string|int, mixed>|false $previous = false ]) : string|false

Stores the token in the database and returns it.

Parameters
$previous : array<string|int, mixed>|false = false

Previous token data, or false to generate new.

Return values
string|false —

The OID token, or false on error.

missing_free_space()

Sets a "missing free space" error message in the response array.

public missing_free_space(array<string|int, mixed> &$return) : string
Parameters
$return : array<string|int, mixed>

The response array (by reference).

Return values
string —

in $return['message'] (the error message)

rest_commands()

Handles hardcoded REST commands that do not require OID (e.g., connection).

public rest_commands() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The response data.

rest_commands_with_oid()

Handles hardcoded REST commands that require OID.

public rest_commands_with_oid() : array<string|int, mixed>

(so you should call "connection" to get first OID before using them)

Each case checks the required parameters, performs the requested file or system operation (such as upload, download, move, copy, delete, lock, etc.), and returns a response array with an HTTP status and message.

These commands are designed for secure, authenticated REST API file management and are executed by the Filesystem ($FS) class.

As they are executed by REST, it's not possible to follow process on very long operation. So it's better to make multiple small operations.

The upd_lock permit also a form of follow, because if it answer that there is no lock on the path, there is no operation on the path. So if one of your process launch a lock/command/unlock, another one can check if it's finished with upd_lock.

NOTE ! At the end of the command, a new OID is returned and should be used for next command !

  • commands:
    • upload_new : Starts a new chunked file upload. Checks for required parameters (destination, filename, size), available disk space, and file existence. Generates an operation ID for the upload session.
    • upload_chunk : Receives a file chunk for an ongoing upload. Checks the operation ID and chunk number, then saves the chunk to a temporary location.
    • upload_end : Finalizes the chunked upload. Verifies all chunks are present, checks file size, merges chunks, moves the file to its final destination, and updates the modification date.
    • download : Handles file download requests. Checks the file path and permissions, then streams the file to the client.
    • ls : Lists the contents of a directory (non-recursive). Checks the path and returns the list of files and folders.
    • recurse_ls : Recursively lists the contents of a directory and its subdirectories.
    • storage_info : Returns information about disk space: total, used, percentage used, and remaining space.
    • move : Moves a file or directory from one location to another. Checks source and destination paths.
    • remove : Deletes a file or directory. Checks the path and performs the deletion.
    • copy : Copies a file or directory to a new location. Checks source and destination paths and available disk space.
    • mkdir : Creates a new directory at the specified path.
    • get_path_perm : Returns the permissions for a given path.
    • lock : Places a lock on a file or directory to prevent concurrent access.
    • unlock : Removes a lock from a file or directory.
    • upd_lock : Updates the lifetime of an existing lock.
    • get_time_utc : Returns the current server UTC timestamp in milliseconds.
Return values
array<string|int, mixed> —

The response data with http "status" and a new OID !

return_response()

Formats and sets the response data, encrypting if needed.

public return_response(array<string|int, mixed> $resp) : void

Throws an exception if status > 200.

Parameters
$resp : array<string|int, mixed>

The response array.

Tags
throws
Exception

If status > 200.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results