lib/external/externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * external API for core library
  20  *
  21  * @package    core_webservice
  22  * @category   external
  23  * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 require_once("$CFG->libdir/externallib.php");
  30
  31 /**
  32  * Web service related functions
  33  *
  34  * @package    core
  35  * @category   external
  36  * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38  * @since Moodle 2.4
  39  */
  40 class core_external extends external_api {
  41
  42
  43     /**
  44      * Format the received string parameters to be sent to the core get_string() function.
  45      *
  46      * @param array $stringparams
  47      * @return object|string
  48      * @since 2.4
  49      */
  50     public static function format_string_parameters($stringparams) {
  51         // Check if there are some string params.
  52         $strparams = new stdClass();
  53         if (!empty($stringparams)) {
  54             // There is only one string parameter.
  55             if (count($stringparams) == 1) {
  56                 $stringparam = array_pop($stringparams);
  57                 if (isset($stringparam['name'])) {
  58                     $strparams->{$stringparam['name']} = $stringparam['value'];
  59                 } else {
  60                     // It is a not named string parameter.
  61                     $strparams = $stringparam['value'];
  62                 }
  63             }  else {
  64                 // There are more than one parameter.
  65                 foreach ($stringparams as $stringparam) {
  66
  67                     // If a parameter is unnamed throw an exception
  68                     // unnamed param is only possible if one only param is sent.
  69                     if (empty($stringparam['name'])) {
  70                         throw new moodle_exception('unnamedstringparam', 'webservice');
  71                     }
  72
  73                     $strparams->{$stringparam['name']} = $stringparam['value'];
  74                 }
  75             }
  76         }
  77         return $strparams;
  78     }
  79
  80     /**
  81      * Returns description of get_string parameters
  82      *
  83      * @return external_function_parameters
  84      * @since Moodle 2.4
  85      */
  86     public static function get_string_parameters() {
  87         return new external_function_parameters(
  88             array('stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
  89                   'component' => new external_value(PARAM_COMPONENT,'component', VALUE_DEFAULT, 'moodle'),
  90                   'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
  91                   'stringparams' => new external_multiple_structure (
  92                       new external_single_structure(array(
  93                           'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
  94                             - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
  95                           'value' => new external_value(PARAM_TEXT,'param value'))),
  96                           'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
  97                    )
  98             )
  99         );
 100     }
 101
 102     /**
 103      * Return a core get_string() call
 104      *
 105      * @param string $identifier string identifier
 106      * @param string $component string component
 107      * @param array $stringparams the string params
 108      * @return string
 109      * @since Moodle 2.4
 110      */
 111     public static function get_string($stringid, $component = 'moodle', $stringparams = array()) {
 112         $params = self::validate_parameters(self::get_string_parameters(),
 113                       array('stringid'=>$stringid, 'component' => $component, 'stringparams' => $stringparams));
 114
 115         return get_string($params['stringid'], $params['component'],
 116             core_external::format_string_parameters($params['stringparams']), $params['lang']);
 117     }
 118
 119     /**
 120      * Returns description of get_string() result value
 121      *
 122      * @return string
 123      * @since Moodle 2.4
 124      */
 125     public static function get_string_returns() {
 126         return new external_value(PARAM_TEXT, 'translated string');
 127     }
 128
 129     /**
 130      * Returns description of get_string parameters
 131      *
 132      * @return external_function_parameters
 133      * @since Moodle 2.4
 134      */
 135     public static function get_strings_parameters() {
 136         return new external_function_parameters(
 137             array('strings' => new external_multiple_structure (
 138                     new external_single_structure (array(
 139                         'stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
 140                         'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_DEFAULT, 'moodle'),
 141                         'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
 142                         'stringparams' => new external_multiple_structure (
 143                             new external_single_structure(array(
 144                                 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
 145                                     - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
 146                                 'value' => new external_value(PARAM_TEXT, 'param value'))),
 147                                 'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
 148                         ))
 149                     )
 150                 )
 151             )
 152         );
 153     }
 154
 155     /**
 156      * Return multiple call to core get_string()
 157      *
 158      * @param array $strings strings to translate
 159      * @return array
 160      *
 161      * @since Moodle 2.4
 162      */
 163     public static function get_strings($strings) {
 164         $params = self::validate_parameters(self::get_strings_parameters(),
 165                       array('strings'=>$strings));
 166
 167         $translatedstrings = array();
 168         foreach($params['strings'] as $string) {
 169
 170             if (empty($string['lang'])) {
 171                 $lang = $string['lang'];
 172             } else {
 173                 $lang = current_language();
 174             }
 175
 176             $translatedstrings[] = array(
 177                 'stringid' => $string['stringid'],
 178                 'component' => $string['component'],
 179                 'lang' => $lang,
 180                 'string' => get_string($string['stringid'], $string['component'],
 181                     core_external::format_string_parameters($string['stringparams']), $lang));
 182         }
 183
 184         return $translatedstrings;
 185     }
 186
 187     /**
 188      * Returns description of get_string() result value
 189      *
 190      * @return array
 191      * @since Moodle 2.4
 192      */
 193     public static function get_strings_returns() {
 194         return new external_multiple_structure(
 195             new external_single_structure(array(
 196                 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
 197                 'component' => new external_value(PARAM_COMPONENT, 'string component'),
 198                 'lang' => new external_value(PARAM_LANG, 'lang'),
 199                 'string' => new external_value(PARAM_TEXT, 'translated string'))
 200             ));
 201     }
 202
 203      /**
 204      * Returns description of get_component_strings parameters
 205      *
 206      * @return external_function_parameters
 207      * @since Moodle 2.4
 208      */
 209     public static function get_component_strings_parameters() {
 210         return new external_function_parameters(
 211             array('component' => new external_value(PARAM_COMPONENT, 'component'),
 212                   'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
 213             )
 214         );
 215     }
 216
 217     /**
 218      * Return all lang strings of a component - call to core get_component_strings().
 219      *
 220      * @param string $component component name
 221      * @return array
 222      *
 223      * @since Moodle 2.4
 224      */
 225     public static function get_component_strings($component, $lang = null) {
 226
 227         if (empty($lang)) {
 228             $lang = current_language();
 229         }
 230
 231         $params = self::validate_parameters(self::get_component_strings_parameters(),
 232                       array('component'=>$component, 'lang' => $lang));
 233
 234         $stringmanager = get_string_manager();
 235
 236         $wsstrings = array();
 237         $componentstrings = $stringmanager->load_component_strings($params['component'], $params['lang']);
 238         foreach($componentstrings as $stringid => $string) {
 239             $wsstring = array();
 240             $wsstring['stringid'] = $stringid;
 241             $wsstring['string'] = $string;
 242             $wsstrings[] = $wsstring;
 243         }
 244
 245         return $wsstrings;
 246     }
 247
 248     /**
 249      * Returns description of get_component_strings() result value
 250      *
 251      * @return array
 252      * @since Moodle 2.4
 253      */
 254     public static function get_component_strings_returns() {
 255         return new external_multiple_structure(
 256             new external_single_structure(array(
 257                 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
 258                 'string' => new external_value(PARAM_RAW, 'translated string'))
 259             ));
 260     }
 261 }