MOBILE-3109 scripts: Create a script to convert PHP to TS

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
 }

scripts/get_ws_ts.php

@@ -0,0 +1,69 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * 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";

scripts/ws_to_ts_functions.php

@@ -0,0 +1,138 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * 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 "";
+    }
+}

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.
  */