[Summary view] [Print] [Text view]

   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 <[email protected]>
  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 <[email protected]>
  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 Moodle 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  }