diff --git a/scripts/functions.sh b/scripts/functions.sh index ed1472357..87e5e5c43 100644 --- a/scripts/functions.sh +++ b/scripts/functions.sh @@ -21,16 +21,19 @@ function print_success { function print_error { tput setaf 1; echo " ERROR: $1" + tput setaf 0 } function print_ok { tput setaf 2; echo " OK: $1" echo + tput setaf 0 } function print_message { tput setaf 3; echo "-------- $1" echo + tput setaf 0 } function print_title { @@ -38,4 +41,5 @@ function print_title { echo tput setaf 5; echo "$stepnumber $1" tput setaf 5; echo '==================' + tput setaf 0 } \ No newline at end of file diff --git a/scripts/get_ws_ts.php b/scripts/get_ws_ts.php new file mode 100644 index 000000000..4c93260ec --- /dev/null +++ b/scripts/get_ws_ts.php @@ -0,0 +1,69 @@ +. + +/** + * Script for converting a PHP WS structure to a TS type. + * + * The first parameter (required) is the path to the Moodle installation to use. + * The second parameter (required) is the name to the WS to convert. + * The third parameter (optional) is the name to put to the TS type. Defaults to "TypeName". + * The fourth parameter (optional) is a boolean: true to convert the params structure, + * false to convert the returns structure. Defaults to false. + */ + +if (!isset($argv[1])) { + echo "ERROR: Please pass the Moodle path as the first parameter.\n"; + die(); +} + + +if (!isset($argv[2])) { + echo "ERROR: Please pass the WS name as the second parameter.\n"; + die(); +} + +$moodlepath = $argv[1]; +$wsname = $argv[2]; +$typename = isset($argv[3]) ? $argv[3] : 'TypeName'; +$useparams = !!(isset($argv[4]) && $argv[4]); + +define('CLI_SCRIPT', true); + +require($moodlepath . '/config.php'); +require($CFG->dirroot . '/webservice/lib.php'); +require_once('ws_to_ts_functions.php'); + +// get all the function descriptions +$functions = $DB->get_records('external_functions', array(), 'name'); +$functiondescs = array(); +foreach ($functions as $function) { + $functiondescs[$function->name] = external_api::external_function_info($function); +} + +if (!isset($functiondescs[$wsname])) { + echo "ERROR: The WS wasn't found in this Moodle installation.\n"; + die(); +} + +if ($useparams) { + $structure = $functiondescs[$wsname]->parameters_desc; + $description = "Params of WS $wsname."; +} else { + $structure = $functiondescs[$wsname]->returns_desc; + $description = "Result of WS $wsname."; +} + +echo get_ts_doc(null, $description, '') . "export type $typename = " . convert_to_ts(null, $structure, $useparams) . ";\n"; diff --git a/scripts/ws_to_ts_functions.php b/scripts/ws_to_ts_functions.php new file mode 100644 index 000000000..c6eb60332 --- /dev/null +++ b/scripts/ws_to_ts_functions.php @@ -0,0 +1,138 @@ +. + +/** + * Helper functions for converting a Moodle WS structure to a TS type. + */ + +/** + * Fix a comment: make sure first letter is uppercase and add a dot at the end if needed. + */ +function fix_comment($desc) { + $desc = trim($desc); + $desc = ucfirst($desc); + + if (substr($desc, -1) !== '.') { + $desc .= '.'; + } + + return $desc; +} + +/** + * Get an inline comment based on a certain text. + */ +function get_inline_comment($desc) { + if (empty($desc)) { + return ''; + } + + return ' // ' . fix_comment($desc); +} + +/** + * Add the TS documentation of a certain element. + */ +function get_ts_doc($type, $desc, $indentation) { + if (empty($desc)) { + // If no key, it's probably in an array. We only document object properties. + return ''; + } + + return $indentation . "/**\n" . + $indentation . " * " . fix_comment($desc) . "\n" . + (!empty($type) ? ($indentation . " * @type {" . $type . "}\n") : '') . + $indentation . " */\n"; +} + +/** + * Specify a certain type, with or without a key. + */ +function convert_key_type($key, $type, $required, $indentation) { + if ($key) { + // It has a key, it's inside an object. + return $indentation . "$key" . ($required == VALUE_OPTIONAL ? '?' : '') . ": $type"; + } else { + // No key, it's probably in an array. Just include the type. + return $type; + } +} + +/** + * Convert a certain element into a TS structure. + */ +function convert_to_ts($key, $value, $boolisnumber = false, $indentation = '', $arraydesc = '') { + if ($value instanceof external_value || $value instanceof external_warnings || $value instanceof external_files) { + // It's a basic field or a pre-defined type like warnings. + $type = 'string'; + + if ($value instanceof external_warnings) { + $type = 'CoreWSExternalWarning[]'; + } else if ($value instanceof external_files) { + $type = 'CoreWSExternalFile[]'; + } else if ($value->type == PARAM_BOOL && !$boolisnumber) { + $type = 'boolean'; + } else if (($value->type == PARAM_BOOL && $boolisnumber) || $value->type == PARAM_INT || $value->type == PARAM_FLOAT || + $value->type == PARAM_LOCALISEDFLOAT || $value->type == PARAM_PERMISSION || $value->type == PARAM_INTEGER || + $value->type == PARAM_NUMBER) { + $type = 'number'; + } + + $result = convert_key_type($key, $type, $value->required, $indentation); + + return $result; + + } else if ($value instanceof external_single_structure) { + // It's an object. + $result = convert_key_type($key, '{', $value->required, $indentation); + + if ($arraydesc) { + // It's an array of objects. Print the array description now. + $result .= get_inline_comment($arraydesc); + } + + $result .= "\n"; + + foreach ($value->keys as $key => $value) { + $result .= convert_to_ts($key, $value, $boolisnumber, $indentation . ' ') . ';'; + + if (!$value instanceof external_multiple_structure || !$value->content instanceof external_single_structure) { + // Add inline comments after the field, except for arrays of objects where it's added at the start. + $result .= get_inline_comment($value->desc); + } + + $result .= "\n"; + } + + $result .= "$indentation}"; + + return $result; + + } else if ($value instanceof external_multiple_structure) { + // It's an array. + $result = convert_key_type($key, '', $value->required, $indentation); + + $result .= convert_to_ts(null, $value->content, $boolisnumber, $indentation, $value->desc); + + $result .= "[]"; + + return $result; + } else { + echo "WARNING: Unknown structure: $key " . get_class($value) . " \n"; + + return ""; + } +} diff --git a/src/providers/ws.ts b/src/providers/ws.ts index 1d891cfa3..cb8aa6eed 100644 --- a/src/providers/ws.ts +++ b/src/providers/ws.ts @@ -116,6 +116,91 @@ export interface CoreWSFileUploadOptions extends FileUploadOptions { itemId?: number; } + +/** + * Structure of warnings returned by WS. + */ +export type CoreWSExternalWarning = { + /** + * Item. + * @type {string} + */ + item?: string; + + /** + * Item id. + * @type {number} + */ + itemid?: number; + + /** + * The warning code can be used by the client app to implement specific behaviour. + * @type {string} + */ + warningcode: string; + + /** + * Untranslated english message to explain the warning. + * @type {string} + */ + message: string; + +}; + +/** + * Structure of files returned by WS. + */ +export type CoreWSExternalFile = { + /** + * File name. + * @type {string} + */ + filename?: string; + + /** + * File path. + * @type {string} + */ + filepath?: string; + + /** + * File size. + * @type {number} + */ + filesize?: number; + + /** + * Downloadable file url. + * @type {string} + */ + fileurl?: string; + + /** + * Time modified. + * @type {number} + */ + timemodified?: number; + + /** + * File mime type. + * @type {string} + */ + mimetype?: string; + + /** + * Whether is an external file. + * @type {number} + */ + isexternalfile?: number; + + /** + * The repository type for external files. + * @type {string} + */ + repositorytype?: string; + +}; + /** * This service allows performing WS calls and download/upload files. */