diff --git a/scripts/get_ws_changes.php b/scripts/get_ws_changes.php new file mode 100644 index 000000000..d5b91f9f0 --- /dev/null +++ b/scripts/get_ws_changes.php @@ -0,0 +1,99 @@ +. + +/** + * 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 a number: 1 to convert the params structure, + * 0 to convert the returns structure. Defaults to 0. + */ + +if (!isset($argv[1])) { + echo "ERROR: Please pass the path to the folder containing the Moodle installations as the first parameter.\n"; + die(); +} + + +if (!isset($argv[2])) { + echo "ERROR: Please pass the WS name as the second parameter.\n"; + die(); +} + +define('CLI_SCRIPT', true); +require_once('ws_to_ts_functions.php'); + +$versions = array('master', '37', '36', '35', '34', '33', '32', '31'); + +$moodlespath = $argv[1]; +$wsname = $argv[2]; +$useparams = !!(isset($argv[3]) && $argv[3]); +$pathseparator = '/'; + +// Get the path to the script. +$index = strrpos(__FILE__, $pathseparator); +if ($index === false) { + $pathseparator = '\\'; + $index = strrpos(__FILE__, $pathseparator); +} +$scriptfolder = substr(__FILE__, 0, $index); +$scriptpath = concatenate_paths($scriptfolder, 'get_ws_structure.php', $pathseparator); + +$previousstructure = null; +$previousversion = null; +$libsloaded = false; + +foreach ($versions as $version) { + $moodlepath = concatenate_paths($moodlespath, 'stable_' . $version, $pathseparator); + + if (!$libsloaded) { + $libsloaded = true; + + require($moodlepath . '/config.php'); + require($CFG->dirroot . '/webservice/lib.php'); + } + + // Get the structure in this Moodle version. + $structure = shell_exec("php $scriptpath $moodlepath $wsname " . ($useparams ? 'true' : '')); + + if (strpos($structure, 'ERROR:') === 0) { + echo "WS not found in version $version. Stop.\n"; + break; + } + + $structure = unserialize($structure); + + if ($previousstructure != null) { + echo "*** Check changes from version $version to $previousversion ***\n"; + + $messages = detect_ws_changes($previousstructure, $structure); + + if (count($messages) > 0) { + $haschanged = true; + + foreach($messages as $message) { + echo "$message\n"; + } + } else { + echo "No changes found.\n"; + } + echo "\n"; + } + + $previousstructure = $structure; + $previousversion = $version; +} diff --git a/scripts/get_ws_structure.php b/scripts/get_ws_structure.php new file mode 100644 index 000000000..bfa975ee9 --- /dev/null +++ b/scripts/get_ws_structure.php @@ -0,0 +1,55 @@ +. + +/** + * Script for getting the PHP structure of a WS returns or params. + * + * 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 a number: 1 to convert the params structure, + * 0 to convert the returns structure. Defaults to 0. + */ + +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]; +$useparams = !!(isset($argv[3]) && $argv[3]); + +define('CLI_SCRIPT', true); + +require($moodlepath . '/config.php'); +require($CFG->dirroot . '/webservice/lib.php'); +require_once('ws_to_ts_functions.php'); + +$structure = get_ws_structure($wsname, $useparams); + +if ($structure === false) { + echo "ERROR: The WS wasn't found in this Moodle installation.\n"; + die(); +} + +remove_default_closures($structure); +echo serialize($structure); diff --git a/scripts/get_ws_ts.php b/scripts/get_ws_ts.php index 4c93260ec..900a153b8 100644 --- a/scripts/get_ws_ts.php +++ b/scripts/get_ws_ts.php @@ -20,8 +20,8 @@ * 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. + * The fourth parameter (optional) is a number: 1 to convert the params structure, + * 0 to convert the returns structure. Defaults to 0. */ if (!isset($argv[1])) { @@ -46,23 +46,16 @@ 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); -} +$structure = get_ws_structure($wsname, $useparams); -if (!isset($functiondescs[$wsname])) { +if ($structure === false) { 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."; } diff --git a/scripts/ws_to_ts_functions.php b/scripts/ws_to_ts_functions.php index c6eb60332..ca05d2082 100644 --- a/scripts/ws_to_ts_functions.php +++ b/scripts/ws_to_ts_functions.php @@ -18,6 +18,28 @@ * Helper functions for converting a Moodle WS structure to a TS type. */ +/** + * Get the structure of a WS params or returns. + */ +function get_ws_structure($wsname, $useparams) { + global $DB; + + // 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])) { + return false; + } else if ($useparams) { + return $functiondescs[$wsname]->parameters_desc; + } else { + return $functiondescs[$wsname]->returns_desc; + } +} + /** * Fix a comment: make sure first letter is uppercase and add a dot at the end if needed. */ @@ -136,3 +158,87 @@ function convert_to_ts($key, $value, $boolisnumber = false, $indentation = '', $ return ""; } } + +/** + * Concatenate two paths. + */ +function concatenate_paths($left, $right, $separator = '/') { + if (!is_string($left) || $left == '') { + return $right; + } else if (!is_string($right) || $right == '') { + return $left; + } + + $lastCharLeft = substr($left, -1); + $firstCharRight = $right[0]; + + if ($lastCharLeft === $separator && $firstCharRight === $separator) { + return $left . substr($right, 1); + } else if ($lastCharLeft !== $separator && $firstCharRight !== '/') { + return $left . '/' . $right; + } else { + return $left . $right; + } +} + +/** + * Detect changes between 2 WS structures. We only detect fields that have been added or modified, not removed fields. + */ +function detect_ws_changes($new, $old, $key = '', $path = '') { + $messages = []; + + if (gettype($new) != gettype($old)) { + // The type has changed. + $messages[] = "Property '$key' has changed type, from '" . gettype($old) . "' to '" . gettype($new) . + ($path != '' ? "' inside $path." : "'."); + + } else if ($new instanceof external_value && $new->type != $old->type) { + // The type has changed. + $messages[] = "Property '$key' has changed type, from '" . $old->type . "' to '" . $new->type . + ($path != '' ? "' inside $path." : "'."); + + } else if ($new instanceof external_warnings || $new instanceof external_files) { + // Ignore these types. + + } else if ($new instanceof external_single_structure) { + // Check each subproperty. + $newpath = ($path != '' ? "$path." : '') . $key; + + foreach ($new->keys as $subkey => $value) { + if (!isset($old->keys[$subkey])) { + // New property. + $messages[] = "New property '$subkey' found" . ($newpath != '' ? " inside '$newpath'." : '.'); + } else { + $messages = array_merge($messages, detect_ws_changes($value, $old->keys[$subkey], $subkey, $newpath)); + } + } + } else if ($new instanceof external_multiple_structure) { + // Recursive call with the content. + $messages = array_merge($messages, detect_ws_changes($new->content, $old->content, $key, $path)); + } + + return $messages; +} + +/** + * Remove all closures (anonymous functions) in the default values so the object can be serialized. + */ +function remove_default_closures($value) { + if ($value instanceof external_warnings || $value instanceof external_files) { + // Ignore these types. + + } else if ($value instanceof external_value) { + if ($value->default instanceof Closure) { + $value->default = null; + } + + } else if ($value instanceof external_single_structure) { + + foreach ($value->keys as $key => $subvalue) { + remove_default_closures($subvalue); + } + + } else if ($value instanceof external_multiple_structure) { + remove_default_closures($value->content); + } +}