Merge branch 'MDL-35997-wip1' of git://github.com/mouneyrac/moodle
[moodle.git] / 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/>.
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  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
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 {
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) {
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                     }
73                     $strparams->{$stringparam['name']} = $stringparam['value'];
74                 }
75             }
76         }
77         return $strparams;
78     }
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     }
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));
115         return get_string($params['stringid'], $params['component'],
116             core_external::format_string_parameters($params['stringparams']), $params['lang']);
117     }
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     }
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     }
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));
167         $translatedstrings = array();
168         foreach($params['strings'] as $string) {
170             if (empty($string['lang'])) {
171                 $lang = $string['lang'];
172             } else {
173                 $lang = current_language();
174             }
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         }
184         return $translatedstrings;
185     }
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     }
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     }
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) {
227         if (empty($lang)) {
228             $lang = current_language();
229         }
231         $params = self::validate_parameters(self::get_component_strings_parameters(),
232                       array('component'=>$component, 'lang' => $lang));
234         $stringmanager = get_string_manager();
236         $wsstrings = array();
237         $componentstrings = $stringmanager->load_component_strings($params['component'], $params['lang']);
238         foreach($componentstrings as $stringid => $string) {
239             $wsstrings[$stringid] = $string;
240         }
242         return $wsstrings;
243     }
245     /**
246      * Returns description of get_component_strings() result value
247      *
248      * @return array
249      * @since Moodle 2.4
250      */
251     public static function get_component_strings_returns() {
252         return new external_multiple_structure(
253             new external_single_structure(array(
254                 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
255                 'string' => new external_value(PARAM_TEXT, 'translated string'))
256             ));
257     }